Best Documentation Practices
De Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
Contents |
Best Documentation Practices
Construct over existing articles. If it is not new functionality, use the existing information and complete it according to the defined structure.
Use simple language to clearly describe the functionality.
When there are many concepts to explain at the same time, place them in order of importance or in sequence.
Try to avoid using too many concepts at the same time as this may confuse the reader. A tool that can be used to classify concepts is to identify them by color or different types of letter, this way the user has another point of reference.
The contents generated should have an order that takes the user from the general concept to that with more detail.
Maintain a logical structure for each new article following the Functional Template.
The necessary contents and concepts should be placed in each part of the schema. Bear in mind that nothing is obvious for the user.
Use practical examples and images that describe the functionality clearly.
When necessary, add notes to indicate any exceptions in the functionality or relevant information for using BizAgi.
When the changes are complete review the document carefully and bear in mind:
Write in the impersonal. For example ‘Configure the ….’ in place of ‘You should configure…’
Avoid the excessive or repetitive use of language such as ‘please’ and ‘congratulations’.
Instructions should be short and concise. Whenever possible include an image rather than words.
Use bold letters when making reference to important subjects or parts of an image, e.g. ‘Related Topics’
When making emphasis, use UPPERCASE without bold, to leave the latter for references as above.
Tips
|
Tips |
|
|
