Best practices for User's Manual for application

Looking for other's techniques to provide a user's guide to the customer for how they should interact with the application I'm building.

  Discussion posts and replies are publicly visible

Parents
    1. Make the User's Manual 'Role-based' - that is, either divide the manual into different sections that reflect the different Roles OR divide the Manual into different Features and tag each Feature with the Role(s) that use those Features. The former means all of the Features for a given Role are grouped together, but will repeat the Feature for each Role; for the latter, the Features appear once only but a User will have to be provided an Index to tell them which Feature applies to their Role
    2. Think of what the different 'Entry Points' are for the system. Where does a process begin? What are the triggers for that process? What should a User do in response to those triggers?
    3. Provide some sort of high-level context for what the system is doing as an orientation for every Role
    4. Pictures. Grab screen-shots and annotate them. This will save a LOT of text along the lines of "Do this...then do that...then do something else..."
    5. Provide some worked examples if possible - follow a Case from start to finish for the scope of each Role for each Feature
    6. Consider any exceptions that might need to be handled (both technical and business) and provide information about who already knows what, who needs to know what and what needs to happen next

    ...I'm sure others will have additional ideas/contributions...

  • Great considerations.  What about the interface?  How would I recreate something like the Appian Documentation webpage?

Reply Children
  • I think at that point it depends entirely upon the context in which you User Manual is going to be hosted/used. A lot of organisations use 'Confluence' as their internal 'knowledge-base' and you may find yourself constrained by that desire/mandate to use such. I guess as long as the Application is commercial in some way then whoever is paying the bill will call the shots regarding what you're allowed to use to publish the content (I have to say I'd assumed you meant a paper-based Manual...but even so the suggestions I've made still apply)