Back

Engineering

Get Started with Technical Documentation Writing Best Practices

Whether you love it or you hate it, you still have to do it - 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, use it, interface with fix it, build on it or expand it. Internal 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 out there 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 tools that best fit 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 to someone like you. Keep that in mind when deciding on the language, tone of voice, structure and topics. 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 to write 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 her/him to get to in 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’re going to explain. Just jot down your thoughts, 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 simple and concise. This does not mean you should not write advanced content. On the contrary - make your advanced explanations easy to understand by adding examples from the codebase . Finally, do not take your readers’ knowledge for granted. Make sure to explain everything or add links to terms that 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 read, some watch. 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 agenda 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:

  • Additional sections of the documentation (like how to install)
  • Blogs, webinars, podcasts
  • Knowledge base articles

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, they might perceive the text differently from what you meant, but this will be valuable feedback. After all, they are your target audience. Make corrections according to their suggestions.

10. Create an Updating Plan

Add the “Last updated” date and create a plan for updating the documentation. This is important for making sure it stays relevant and fresh for consumers in the upcoming months and years. Tools like Swimm can help automatically update documentation anytime you update your code.

Startups get up to 12 months complimentary Swimm, sign up here.

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. 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.