When you start thinking about a user guide for your shiny new software product you have to think about
- who will be reading it -> make a list of end users
- where you put it -> it has to be available for all the end users, but also practical for you to work on without changing your whole environment.
Mostly the users of a product are using other tools then the common software developer. They like to read a user guide in their Business Wiki or in a nice formatted PDF or on a shiny web site, which they can reach directly from the product.
As a developer I don´t want to think about formatting and designing a nice document. I want to add my content to a file, start an automation and magically get a readable document that fulfills all those requirements.
Therefore the content of the user guide should be managed in your code repository next to your other work. Markdown files are most suitable for this, because they include the plain text and can be used easily with other tools which do all the magic. You can add one file for each chapter to make it easy to work on each chapter independently, with different people, make reviews and keep them versioned in git.
Add repo in Git and add your markdown files
Add a git repository for your user guide and add some markdown files for the chapters you want to include. The following chapters are examples for chapters commonly used in a user guide:
- Introduction
- Feature Overview
- Getting started
- User interface (step-by-step instructions)
- Advanced Features
- Main Use Cases (Best practices)
- Maintenance
- Troubleshooting
- Frequently asked questions
- Glossary
- Contact information
But of course you can change these to your needs.
Weiterlesen