DEV Community 👩‍💻👨‍💻

Discussion on: How to write clear and concise documentation

Collapse
dougaws profile image
Doug

In the technical writing business, baseline is known as audience analysis.
Once one has settled on an audience, the next step is to determine the general contents of the docs. If the project output is a product, you'll need a basic outline like the following:

  1. About the ...
  2. Installing the ...
  3. Configuring the ...
  4. Using the ...
  5. Reference

Despite the order of chapters, one typically starts with the lowest-level reference first.
Document all inputs, outputs, errors.
If one has time, create a simple example for every function.

And so on.

To really improve your documentation, hire a technical writer. But beware, you'll need to spend time bringing them up to speed, so don't wait until too late in the development cycle.

If the budget allows, also hire an editor (or contract editor if the project is short). The more eyes on docs, the better.

Collapse
erikmelone profile image
Erik Melone Author

Thanks for sharing - as a Software Engineer I am far from a technical writer. I have never been fortunate enough to work with a team that hired a technical writer - us engineers have had to take it upon ourselves to write documentation and this is part of the method I've come up with when I go to write documentation. Having a dedicated technical writer sounds like a dream!