The world’s leading publication for data science, AI, and ML professionals.

Documentation 101: 5 Tools to Help You Create Better Docs

Eliminate the heavy lifting and focus on the content

Photo by Sigmund on Unsplash
Photo by Sigmund on Unsplash

Writing documentation is probably one of the tasks programmers dread the most. I mean, we are programmers and not writers anyway. It is well-known that programmers are great and writing code but not so great at explaining it’s thought process.

I believe that’s why we hate writing documentation so much because then, we need to explain our thought process in words for others to understand. And that’s never a fun task.

Regardless of that, all programmers know the importance of good-written documentation and how essential it is to any coding project’s success, whether it was intended for open-source or as a provide project within a team.

Documenting the writing code steps and the justifications of some design decisions are beneficial for people using the code and those who wrote it when it’s time for adding/ removing new features.

In this article, we will go through 5 tools that help you generate the outline of your documentation, eliminating the need for you to worry about the little details instead of focusing on explaining your code and its usage to others.

№1: Read the Docs

We can’t talk about documentation tools without mentioning Read the docs. Read the docs is what I like to call, in one documentation wonderland. The reason this tool is very well known among the open-source community is read the docs is not only a tool that helps you write documentation, but it also helps you keep everything in sync, with versions, and to top that off, but it also hosts your docs for easy access.

The image is a screenshot by the author.
The image is a screenshot by the author.

Another advantage of reading the docs is, it’s a well-documented documentation tool – see what I did there?. Its getting started guide is all you need to know to start writing documentation without needing to think about hosting servers or the documentation design.

Read the docs is an excellent choice for new programmers to learn and hone their document writing skills.

№2: Github Pages

Whether you’re an open-source programmer, working in a company, or just starting your learning journey, chances are you came across projects on Github and saw how some developers use the project’s repository to provide simple documentation of the code.

The image is a screenshot of the Numpy repo readme file taken by the author.
The image is a screenshot of the Numpy repo readme file taken by the author.

If you’re not creating a standalone documentation site and want everything to be in the same location, you can use the Github readme file to write your code’s documentation. You will need to be familiar with markdown formatting and be okay with having simple one-sheet documentation.

If you want to extend your docs and have multi-sheet documentation, then you can use Github pages to document your code and connect it to your project’s Git repository.

The image is a screenshot by the author
The image is a screenshot by the author

№3: Tettra

The two options we have come across so far allow you to write and host your public use documentation. But, what if you want to write your documentation for internal use only? Meaning only people within your company or team have access to the documentation. What are your choices then?

If you want to host documentation for internal use only, Tettra can be your documentation platform of choice.

The image is a screenshot by the author.
The image is a screenshot by the author.

Tettra was originally built to be used to build companies’ wikis so new people joining in can find all the information they need to adapt to their new work environment. Nevertheless, it can be used to document anything and be used within a local network.

№4: Dropbox Paper

Another tool that you can use to create internal documentation is Dropbox Paper. Dropbox Paper is another great choice for creating a company wiki and sharing information within a local network.

The image is a screenshot by the author.
The image is a screenshot by the author.

It allows you to add code blocks, images, and all information you might need in a documentation tool. It also allows the main authors of documentation to approve or reject collaborators’ edits to the docs’ content.

№5: Process Street

If you’re new to software development or want to have all documentation for all your projects in the same location, then Process Street is the way to go.

The image is a screenshot by the author.
The image is a screenshot by the author.

You can use this tool to create a checklist for all necessary details – sections – you need to add to the documentation and keep and sort all the documentation you have so it can be public and easily accessed by all people in your team or company.

Final Thoughts

Documenting your code is one of the aspects that can make your project a hit or a miss. Although most programmers and developers, despite writing documentation and explaining the magic that makes their code does its task perfectly, no one can deny how important having good documentation is.

If you’re new to the field of writing software for others to use or as a part of a developing team, documentation may – at first – seem as necessary. But, as all of us came to realize, sometimes documenting code can be very critical.

Imagine having a codebase with thousands or millions of lines of code, and you’re asked to add a new feature or remove an existing one. How would you go about doing that if the code was not well-documented?

You’ll probably have to read most of the code, trying to figure out all the connections within that you need to know to do your task without breaking the code.

That sounds bad, doesn’t it?

That’s one of the main reasons documentation should always be on your mind when you’re writing any piece of code, regardless of its complexity.

In this article, we went through 5 tools that you can use to make the process of creating and writing documentation much easier and less of a hassle. And remember, having well-written, easily accessible docs can transform your project and maybe land you your dream job.


Related Articles