Get Started with Technical Documentation Writing Best Practices

Whether you love it or you hate it, you still have to do it - that is, document your code.

Good internal software documentation boosts developer productivity by helping you and your fellow engineers quickly understand the code you’ve written. This is important so in the future, you can return to the code, understand and use it, interface with it, build it, and make changes. Documentation is also valuable for new onboarding, context-switching, and optimizing the development cycle and flow of information within the R&D team.

There are many tools that can help with the technicalities of internal documentation. This post is focused on the writing part.

We’ve put together key best practices that we hope will assist you with the process and with finding the right approach that best fits your documentation and team's needs.

1. Write what you’d like to read

The purpose of the internal technical documentation is to make your code and components understandable to you or someone like you. When deciding on the language, tone of voice, structure, and topics, keep that in mind. Make sure the layout, vocabulary, grammar, and explanations would be clear to a beginner ‘you’ and add value to an expert ‘you.'

2. Plan the documentation

Plan the structure, topics, and flow before you start writing. That way, when you sit down, all you have to do is fill in the blanks.

  1. Decide on the purpose of the documentation. Is it an installation guide, a tutorial, API documentation, or a README file?
  2. Plan your structure and flow, write down:
  • The knowledge point the reader is starting (A)
  • Where you’d like the reader to get to at the end (Z)
  • The different steps they need to go through to get from A to Z

These are your outline and sections.

  1. Fill out each section with thoughts and bullet points about what you will explain. Just jot down your ideas; they do not have to be in an organized or readable format just yet.

3. Explain in a simple yet detailed manner

Your documentation should be easy to consume for your team members. Write in short sentences and keep explanations concise and straightforward. This does not mean you should not write advanced content. On the contrary - add examples from the codebase so it's easy to understand. Finally, do not take your readers’ knowledge for granted. Make sure to explain everything or add links to the terms you are using.

4. Use graphics like images and video

Add images, videos, and graphics to explain the code and architecture. Why? Because:

  • Sometimes explanations are easier conveyed through images: a picture is worth a thousand words.
  • They break up the text, which makes it easier to consume.
  • Different people consume different types of content better; some prefer reading, and others watching. Make sure to address all audiences.

5. Add references and code

Add code snippets (with markup language), libraries, API endpoints, parameters, coding conventions, and additional references to your explanations. Not only will they help you exemplify your points - but they will also make your documentation actionable.

Readers will be able to copy-paste different parts and use them. It is somewhat as if you were sitting right next to them and explaining what to do.

6. Add a table of contents, Quick Start, or high-level bullet points

Introduce the plan for your documentation through a table of contents, bullet points, or a Quick Start page. These will:

  • Prepare the readers for what they will be reading
  • Allow them to skip ahead or return to a certain point
  • Make the content easier to consume visually
  • Improve user experience

7. Refer to additional resources

Let readers expand their knowledge on the topics you’re writing about by referring them to additional resources that can help them learn:

  • Other sections of the documentation (like how to install)
  • Blogs, webinars, podcasts
  • Knowledge base articles
  • Playlists that you may have put together - a collection of documents, links, Markdown files, videos to help your dev team.

8. Help readers find it

For example, if you’re writing documentation for open-source, help readers find you through Google. Add many features and product names to titles and explanations, so Google indexes your text.

9. Go through revisions and get feedback

You’ve completed the document. Congratulations! Now it’s time to get feedback and revise. Let your fellow team members read and review.

Remember, your team might perceive the text differently from what you meant, but if that's the case, this will be valuable feedback. After all, they are your target audience.

Make corrections according to their suggestions.

10. Create an updating plan

Software products, code, and APIs are not always easy for your fellow developers to understand. Even you will have a hard time remembering what you coded a month from now. Documentation helps overcome these gaps by providing a searchable, permanent, single source of knowledge.

Don't forget to include a “Last Updated” date and create a plan for updating the documentation. Tools like Swimm can help automatically update documentation anytime you update your code.

This is important for ensuring it stays relevant and fresh for consumers in the upcoming months and years.

Bottom Line

Our recommendation: practice writing to gain writing muscle memory and make writing documentation a habit. You will help developers onboard to your code and boost your own productivity.

Sign up for Swimm's free beta and/or request to see a demo.