Need consistent formatting/organization within documentation

Michael Magoon shared this problem 7 years ago

On your support forum, I have seen some griping about the quality of the documentation. Overall, I think they are wrong, but with some simple changes, I think you can dramatically enhance the usability of your documentation.

The main problem is a lack of a consistent use of formatting and organization. Each section is organized a bit differently and each has its own formatting. It makes it very hard to quickly skim a section and find exactly what you are looking for. In many cases, the important information is there, but it is hard to find. And the formatting of the user guide is different from the formatting of the help.

I have been a software technical writer for 13 years, and the following organization works very well.

Most importantly, the documentation needs to be task-based. Users don't care so much what a button does, so much as the step-by-step instructions as to how to do their task. This is often missing or difficult to find because of the formatting.

1) Main Heading: Item you are discussing (for example templates). Bold font and big text.

2) Brief description about that item.

3) Sub-heading related to one task (for example: creating a template). This should be bold font.

4) Brief description about task (if necessary)

5) Step-by-step instructions on how to accomplish task. This should use numbers and bullets. This is the most important formatting as it enables users to find the critical steps fast. In many cases, these steps are in bold text. That makes it much harder to find than numbering.

6) Repeat 3-5 for the next task.

All of the headings and sub-heading should be in an index at the back of the User Guide.

For some more complex widgets (for example, Dynamic Panel), mini-tutorials guiding the user step-by-step on how to create a common Dynamic Panel would be extremely useful. Creating the Amazon 5-star review widget might be an example.

The Actions and Expressions section could also use some mini-tutorials.

Hope that helps.

Comments (3)


By the way, the Tutorial doc does have some very good mini-tutorials (for example, how to create log-in validation condition, etc). I would like to see more of the same.


We are willing and we are in our way to improve the documents and videos. Now we are focusing our efforts in some 'surprises' we are going to launch in the next months so we don't have the time to do it. But once we finish that we will go straight into the documents for sure.


We've just added the mini-tutorials to our learn section Thanks Michael!