What are your best practices for writing documentation?

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?

Did you find this post useful? Show some love!
DISCUSSION (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:

  • Getting Started (markdown formatting, how to deploy)
  • Next Steps (Selecting a theme)
  • Advanced (Creating a theme, custom domain names). ### Lead with uses cases One of the first things I'm trying to understand when I find a new npm package, phone app, or open source repo is to understand why I would want to use it. In fact, when I find a repo that I need to use which doesn't have a good readme with use cases explained, I make one and open a pull request.

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.

Classic DEV Post from Oct 8

Hiring process of your dreams

What would be a hiring process you would love?

READ POST
Follow @leonorader to see more of their posts in your feed.
Mike
Senior full stack developer; speaker; 12 years in development; manages a team of over 20 talented developers
More from @michaelgv
Looking for beta testers for Edge Application Delivery Network
#edge #askdev
Online Dev Conference - Call for speakers
#discuss #askdev #showdev #conference
Trending on dev.to
Discuss: What is your Myers-Briggs Type Indicator (MBTI)?
#discuss #nontech #selfimprovement #productivity
Best Job Types while Learning To Code
#discuss #question #learning
Who's looking for open source contributors? (October 15th edition)
#discuss #opensource #hacktoberfest
What discontinued company/product do you wish was still around?
#discuss
Dev.to Review #3: Top 7 Of The Week, Discussed
#discuss #audio #bestofdev #popular
Why we chose Turbolinks instead of building an SPA
#javascript #webdev #productivity #elixir
Who is hiring? (As of October 2018)
#whoishiring #discuss
Let's talk about the state of auto-generated documentation tools for JavaScript
#discuss #javascript #tools