Suppose you've been tasked with writing documentation about a project you've been highly involved in it's creation, from start to finish you had a voice in it - how would you go about writing documentation that is customer friendly, while maintaining key knowledge such as system functionality, order of operations, with mock data?
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (4)
Except for the user manual, I had to keep, a minimal doc of type:
high level, of how things work at a very abstract level, describing the business problem and 10000 feet implementation - keep it simple and use images, can be replaced by the actual task description.
user manual - the users of the system, is like a Help, this is the most difficult to keep it up to date, and usually requires copywriters that are kept in the development loop. For non-technical people so avoid buzzwords and technical details.
technical docs - how systems works, where are they hosted, how to make a local setup, data/user flow diagrams, what algorithms are used, what techniques and so on, configs, APIs documentation. This can be understood by any engineer/QA/lead/architect.
The trick here was to update it each sprint, I usually done this while the task was at QA and I had downtime. They have to be related to tasks (2way links) so best place for them was in the project management software/wiki.
developer only - usually code comments, automatic tests, classes diagrams.
This were pretty much done as going, keeping them in the project or some in wiki.
Use version control!
Before you do anything else, version control is just as important for documentation as it is for the underlying code. As a project continues to evolve, so will the docs. This can be hard, depending on what platform you are using to host the documentation. For a past project, I used slate which allowed me to utilize Git. Check if you can use Git, markdown files (or another markup file to store in Git), and if your docs platform supports backups.
Think about user personas
Once you've been working on a project long enough, it is easy to lose sight of what a newbie would need to know. Spend some time to write down who you think will use the docs, what knowledge you think they will already have, and what knowledge they won't have. Use that context to guide your information architecture.
As an example, if I were documenting how to create a webpage hosted on GitHub pages, I would split things up into something like:
Depending on what you are documenting, there's two core ways to cover this. The first is with sample code. Twilio has a great example of this on their SMS landing page which reads "Send your first message" as a call to action. The second method is to write exactly what you intended the project to be used for, what you didn't intend it for, and what others have done with it so far.
Take feedback
Make sure you have a mechanism for finding out how good your documentation is. Try to avoid anything that requires a login (e.g. GitHub issues). If you can't, that's okay but keep in mind that it creates a barrier to getting actionable insights. You can capture feedback using a feedback form, a public trello board, a community forum, a subreddit, et al.
Add website analytics
Another good addition is Google Analytics. It will allow you to see how long someone stays on a page, what page they enter the site from, and where your users are coming from.
I give you a hint: I don't!
Joke aside, it higly depends on what I need to tell to whom.
Suppose it's your boss?