The user manual is too verbose and text-heavy

[aviflax]

As far as I can tell, the docs are not particularly effective; they’re mostly just walls of text that people tend to skim, so they miss things. The docs need to be improved.

Let’s discuss these problems in more detail and consider potential improvements together.

[aviflax]

I feel it’d probably be helpful to consider a concrete example:

Case 1: Image Rendering

Recently @cassiomarques asked me how to export a PNG diagram image from Structurizr Express to update a PNG file in Funding Circle’s private docs repository. Which is an extremely reasonable question, but since this is such a critical step of the workflow, it would have been better if he had gleaned this information from the methodology docs.

So let’s take a look at how this information is currently conveyed in the docs, and discuss why and how it’s not sufficiently effective, and what we can do to improve it.

The info is buried in step 10.2 of The Authoring Workflow:

and for visual context here’s a screenshot of most of the page:

as you can see, it’s not quite a wall of text… maybe more like a tree (🤓) but regardless, it’s clearly not very effective.

So… what is the problem here? Just too much text? Do we need to add a summary to the top of the page, with the current list becoming the "in detail" section for reference? Or is the workflow itself just a mess, and we should focus on streamlining it by improving our tools and their integration?

[fussybeaver]

There could possibly be a TLDR, because in effect the workflow really describes two things: importing something from fc4 to SE, and then a unidirectional workflow to export back to fc4, there is a lot of recommendations aside from this, which is useful but maybe not relevant to whoever just wants to work without reading everything in one go.

[aviflax]

@fussybeaver that makes sense; I’ll see if I can come up with a summary. Thanks!

[cassiomarques]

Maybe adding images after steps, showing what the text is talking about, would help. Even though we have a wall (or tree) of text, if we had some screenshots there that would make the documentation a bit less dry.

[aviflax]

@cassiomarques that makes sense, I’ll give it a try, thanks!

[holyjak]

FYI I am new to FC4 and just went through the docs to get to know it and they seem fine to me. Of course they can (always) be improved.

The changes I can think of is to add a short description to each of the links at https://fundingcircle.github.io/fc4-framework/methodology/ (to answer "why do I want to read this"?) and, perhaps, close to the top of https://fundingcircle.github.io/fc4-framework/ a link to a Getting Started guide that would be a quick tutorial for getting the tool, creating and modifying a simple diagram [set], publishing, reviewing. Focusing on communicating what the tool does, how is it used, leveraging examples, without going into details (but linking to them).

[aviflax]

Thanks @holyjak I very much appreciate the feedback and suggestions!

I’ll try those links, and I’ve already got a Getting Started guide under way… unfortunately I tied it to some new features, so in order to publish it, I need to either refactor it to explain the current functionality, or release those new features 🙄.

Thanks so much!

[aviflax]

(In #257 the methodology docset was refactored to be the user manual. I don’t think that has a material impact on this issue.)