One of the hardest parts of writing software is documenting it. In order to write good software documentation, you need to use the right software documentation tools. Trying to open a gate with a chainsaw instead of using a key would be painful and time-consuming. Especially if you don’t really enjoy the process of doing it.
Most software engineers write the documentation for a project at the end of a sprint or they dedicate a separate sprint at the end of the development phase. At that point, they probably have already memorized most of the functions and writing software documentation can seem very cumbersome and useless. To make this process easier, there are several software documentation tools available.
Why is software documentation important?
Without documentation, software resembles a black box. It is useful and it probably gets the job done, but it can’t be altered based on your needs. Even the best-written software can turn useless if other developers or users are unable to understand it. Documentation is what turns your black box into a glass box.
What does software documentation include?
If you search for the documentation of any big company, Tallyfy included, you will notice that the documentation can consist of the requirements of the system, its architecture, an explanation of the algorithms and code, API specifications and more.
Types of Software Documentation Tools
There are different formats and editors that can be used to write a well-structured documentation. The most common one is documentation written in markdown format. Documentation written in Markdown format can be done either through a Markdown Desktop Text Editor (installed on your local machine), a Markdown In-Browser Online Editor, or Automatic Generation Software Documentation Tools, such as LaTex (generally used by academia and scientific documentation).
Markdown Desktop Editors
Markdown is probably the most widespread form of writing software documentation. It is a lightweight markup language that can easily be converted into HTML or other formats. What makes markdown one of the top choices is the fact that you can use almost any plain text editor to create markdown files.
Different text editors and extensions have been created to make the process of writing markdown even easier. We analyze the most prominent ones below.
Texts
Texts is supported both on Windows and Mac OS. It provides a visual representation of the markdown text, thus making it an easy to use software documentation tool for beginners. You don’t need to remember the markdown syntax and images are visualized directly within the text. Additionally, it provides portability and allows for conversion between different formats such as PDF, Word, ePub etc.
Another great feature that Texts provides is the integration with reference management applications and the bibliography support in standard BibTex format.
The text editor is customizable and you can choose from a set of themes. The only drawback is that it is not free. It costs $19 per user regardless of whether you are purchasing it as a team or as an individual.
A great drawback, however, is that in order to work with Texts, you must first install Pandoc, which is a universal document text converter.
Typora
This text editor is supported on all three main operating systems, Windows, Mac OS and Linux. Unlike Texts, Typora offers a file management system which can connect directly to any cloud service such as Google Drive or Dropbox. The outline panel on the side of the editor makes navigating through documentation much easier.
A noteworthy feature that Typora provides is its seamless live preview. The editor shows the modifiable markdown code only when the cursor is pointing at that specific position. When the cursor leaves the text, the markdown is hidden.
Additionally, Typora provides a range of built-in themes while also allowing users to create their own themes using CSS. The main drawback is that the text editor is currently in beta version and several features might change until the final release version. Many users don’t enjoy getting used to a text editor and then finding out that the new release is completely different from what they have been using all the time.
Since the editor is provided for free only while it is in Beta version, the final release will also result in users having to pay for using the editor.
Haroopad
Haroopad provides cross-platform support just like most of the other editors analyzed so far (Windows, Linux, and Mac OS). Its primary statement is that the experience of using the editor should be the same regardless of the operating system in which it runs.
This editor stands out because it provides some advanced features that most developers would appreciate. It supports vim key binding and more than 100 different programming languages with syntax highlighting.
Haroopad has four different display modes. The default mode features a split screen (Editor:Viewer). Then there are the Reverse (Viewer:Editor), Viewer only and Editor only modes.
A distinguishing feature as a software documentation tool is that it allows developers to draw flowcharts or sequence diagrams in order to visually represent workflows.
This markdown editor is provided for free. However, it seems that work on the GitHub repository has halted for the past two or three years. Haroopad will likely remain in Beta version unless some casual developer decides to complete it.
MarkdownPad
MarkdownPad is probably one of the most popular markdown editors for Windows. Its greatest drawback is that it runs only on Windows. Apart from that, it offers a wide variety of features.
The split screen with a live preview makes it very easy to edit documentation. However, it does not provide a seamless live preview like Typora does. Moreover, just like most of the other software documentation tools, MarkdownPad offers CSS customizability supporting multiple stylesheets.
The UI is very easy to learn, understand and use. It’s a very simple window with two toolbars, however, offering great customizability and efficiency. The latest version of MarkdownPad is MarkdownPad2.
Another important Markdown editor that I personally like to use and visually resembles MarkdownPad, is Visual Studio Code. Unfortunately, since the release of markdown extensions for VS Code, MarkdownPad has not been maintained and there is almost no activity on GitHub for it.
Visual Studio Code
The primary drawback of Visual Studio Code is that it does not support markdown editing by default. This means you need to install an extension. However, this is done directly from the application and requires no more than two mouse clicks.
What I like about using Visual Studio Code for markdown is that it offers a wide range of extensions for Markdown editing. For example, one extension can have a seamless live preview and also offer a bunch of other useful features. Another extension can offer different themes, whereas another extension provides live document preview on your browser so that you can preview the documentation you are creating as it would be treated as an HTML file.
Finally, VS Code looks very similar to Visual Studio, an application used by most programmers that deal with Microsoft technologies.
SimpleMDE
SimpleMDE is a simple and embeddable javascript markdown editor. The primary advantage is that this software documentation tool is open source and thus its repository can be forked from GitHub. Using it is free and the project can serve as a learning experience for other people to experiment and create their own markdown editor.
The project can be seen on Github or downloaded as a .zip or .tar.gz file. After playing around with it for a bit, we came to the conclusion that this markdown editor might not be as straightforward to use as the other editors and it requires some small technical knowledge from the user’s side.
Its biggest advantage is probably the extensive set of features it has to offer while not having to pay for it.
Sublime Text 3
Sublime Text is one of the most well-known text editors for programmers. It runs on Windows, Linux and Mac OS. Moreover, it comes with a plethora of cool features, but it does not support markdown editing by default.
Out of all the software documentation tools we have compared, Sublime Text is probably the most difficult one to set up. Installation is not straightforward since it first requires the installation of the Sublime Package Control and then the installation of the Markdown Editing Package.
Additionally, this editor comes at a price of $70 per user. If you only need a text editor to write markdown format software documentation, then Sublime Text is probably an overkill. It provides so many features that can be useful to programmers and developers but not as much to web writers.
The price, installation requirements and the set of offered features make this documentation tool a good fit for advanced users that can make the most out of the provided toolset. Inexperienced users who are looking for a simple markdown editor are probably better off with a different one.
Notepad++
Notepad++ is probably one of our favorite text editors. It runs on all three top operating systems and resembles very closely the default Windows Notepad application. However, it comes with a set of more advanced features. It’s a Notepad on steroids.
Asides from supporting different programming languages, Notepad++ allows us to create markdown files and thus use it as a software documentation tool. Certainly, it is not a dedicated application for writing documentation, but if you are already using Notepad++ in your daily work and feel comfortable using it, then why not.
At Tallyfy we also enjoy Notepad++ due to their frequent updates and because it is free.
Inkdrop
Inkdrop is a note taking app for markdown lovers. We were quite hyped when I discovered it, to be honest. The app has a very slick UI and runs on all three main operating systems plus IOS and Android.
Our hype started fading away when we saw that you need to pay $4.99/month or $49.90 yearly. If we compare this note taking app to similar competitors like Evernote, we would say that the price of Inkdrop is quite convenient. However, since most users don’t want to think in terms of markdown when taking notes, people still prefer Evernote to Inkdrop.
Funnily enough, even the design of Inkdrop’s interface is very similar to Evernote’s interface. Furthermore, since most of the data is stored in the cloud, Inkdrop offers a good layer of security through an encryption with a 256-bit AES common key.
In terms of features, it provides a distraction-free setup, with a side-by-side live preview. Additionally, it offers code and syntax highlighting as well as key customizations.
Markdown In-Browser Online Editors
Stackedit
Stackedit is an in-browser markdown editor with a very slick and simple user interface. Asides from offering a set of advanced features and different syntax highlighting mechanisms, it also provides WYSIWYG controls, handy formatting buttons, and shortcuts.
The editor has a built-in spell checking software and the themes, layouts and shortcuts are all fully customizable. Stackedit was made considering the needs of web writers. Possibly the biggest advantage of Stackedit is the easiness with which you can directly upload your software documentation on different platforms like GitHub, Youtube, Google Drive, WordPress etc..
Additionally, the files can be saved in markdown or HTML format. If two or more people are collaborating on writing the documentation, Stackedit takes care of merging changes even when collaborators work on it simultaneously.
Ultimately, this editor allows you to work even while being offline just like any other desktop application. When you connect to the wifi it syncs everything automatically. On a more technical side, UML diagrams and flowcharts are very easy to make using the respective markdown syntax.
Dillinger
Dillinger is also an in-browser markdown editor with a very simple design and interface. As soon as you open Dillinger, you find yourself with a split screen featuring an example of a markdown document.
Apart from being very easy to use, Dillinger also offers several ways to easily preview, export or save a software documentation. The documentation can be viewed in HTML, styled HTML, Markdown, and PDF. The file can then be exported in the same formats mentioned before. Additionally, the software documentation can be directly saved to Dropbox, Google Drive, OneDrive, Github or Medium.
The left sidebar makes it very easy to link documents from other sources or to organize imported and saved documents. Moreover, Dillinger provides a scroll syncing mechanism.
Editor.md
Editor.md is a web-based open source markdown editor. It comes with a very simple user interface, containing just one toolbar and the viewing screen.
Asides from the markdown editor itself, there are separate projects being developed simultaneously to increase the number of features for it. Katex, for example, is used to integrate Latex formulas, which we will discuss further below. It is mainly used for including mathematical formulas in software documentation.
The creators of this software documentation tool have also written many examples which can serve as a learning aid to master the art of writing software documentation using markdown.
Asides from using markdown, there are different other software documentation tools.
Automatic generation software documentation tools
Some software documentation tools are more automatic and can greatly improve the time it takes developers to write the documentation.
Swagger
One of these tools is Swagger. It is not just a software documentation tool but it also serves to design and build APIs. However, within the context of this post, we only analyze Swagger as a documentation tool.
For most web developers that build RESTful APIs, Swagger has been a powerful ally. For example, .NET developers only need to include XML comments for each function or endpoint and then Swagger automatically generates a detailed documentation for the API.
Doxygen
Doxygen can be used to automatically generate documentation from C++ code. Lately, it has started supporting other languages as well. Some of the most well-known are C, Objective-C, C#, PHP, Java, Python, Fortran etc.
The best thing about Doxygen is that it is free and runs on all three main operating systems. Additionally, it allows you to create both HTML format documentation as well as offline reference manuals in LaTex.
GhostDoc
GhostDoc is a Visual Studio extension that automatically generates XML documentation comments for methods and properties based on their type or the context in which they are declared.
It supports .NET languages (C#, Visual Basic), Javascript. Moreover, in terms of payment, GhostDoc offers a free version that includes most necessary features and also has a Pro version for $50/user and an Enterprise version which costs $160/user.
JavaDoc
As the name suggests, JavaDoc is a software documentation tool that automatically generates documentation while only supporting Java as a programming language. If your first language of choice happens to be Java then this is the perfect tool for you.
LaTex
Markdown is probably the most popular markup language for writing documentation, however, other languages such as LaTex exist. LaTex is a document preparation system and is mainly used in writing scientific papers, technical papers or scientific project documentation. As such, it is probably the most widespread software documentation tool among academia.
LaTex is available cross-platform, on Windows, Linux, and Mac OS. Additionally, LaTex can also be used online through external services such as Papeeria, Overleaf, ShareLaTex, or Datazar.
Just like with markdown, when using Latex you need to use the specified markup language in order to structure your documentation. Learning the syntax to the point where you are proficient and can type a document really fast, takes some practice. However, once you get used to it, you start seeing the benefits of using LaTex instead of outdated text editors like Microsoft Word.
The greatest things about LaTex is that is was created with the purpose of removing the burden of document design from the developer. When writing documentation, one should focus on getting the content right instead of worrying about the font style or size. LaTex makes it such that designers will have to worry later on about how the document should look. This can save software developers a lot of time.
The greatest advantage of using LaTex is that it is free and there are plenty of editors that support it. Additionally, any research institutions, universities or even passionate individuals create documentation templates that can easily be imported into LaTex and used as a sample for writing software documentation.
Recap and Conclusions
As we saw above, there are different formats and different software documentation tools that support those formats. The two most common markup languages used are Markdown and Latex. The latter being mainly used in academia and scientific publications.
From the Markdown editors, we can choose among desktop application text editors and in-browser online editors. Almost all of them provide the minimally required features expected from software documentation tools. In the end, the choice boils down to whether we are willing to pay some money for extra features or we are fine with using a free editor. Apart from this, any editor will get the job done if you are used to working with it.
Automatic software documentation tools can also be used depending on the programming language that the developer is using. Javadoc for example only supports Java as a programming language. These tools are very efficient and greatly reduce documentation writing time, however, they come at the cost of being incomplete and not as detailed as one might require them to be.
Finally, LaTex is one of the most important software documentation tools since it provides probably the most complete set of mathematical representations and it is globally adopted by academia and scientific communities.
Hopefully, this post gave you a better understanding of the available software documentation tools and will serve as a stepping stone for choosing the best tool for you. If you think we might have missed something, or want to share your experience with software documentation tools, let us know down in the comments!
