8/24/2016

18 Software Documentation Tools that Do The Hard Work ForYou

process.st/software-documentation/

Benjamin Brandall

August 24, 2016

Without documentation, software is just a black box. And black boxes aren’t anywhere near as useful as they couldbe because their inner workings are hidden from those who need them in the open.

Software documentation turns your software into a glass box by explaining to users and developers how theit operates or is used.

You’ve probably seen documentation before, but if you need a refresher, here’s an example from Slack‘s API:

1/12

As you can see, Slack explains everything about its API in excruciating detail. Any related pages are linked, there’s asidebar with easy-to-access topics, and screenshots of what the user can expect to see.

Documentation can be as simple as a README.MD file in the repository, and it can be as complex as an entiresubdomain with a custom design like Slack’s API docs (above). Whatever you choose, there are several tools to useto make the process easier.

Writing tools for software documentation

Software documentation is often written in markdown to allow for hyperlinks and formatting while keeping it plain textso it can live alongside the code files in version control. That means that a lot of my choices for writing tools aresimple markdown editors that make the writing experience enjoyable. Additionally, there are also a couple of veryeffective non-mparkdown solutions thrown in there.

MarkdownPad (Windows)

With a free and premium version — both with a ton of great features — MarkdownPad is the most popularmarkdown editor for Windows. It’s optimized for blog posts, websites, articles, READMEs, and, of course, softwaredocumentation.

2/12

You can get MarkdownPad for free, or get the premium version for $14.95.

iA Writer (Mac)

iA Writer is a simple, beautiful markdown editor with a library feature meaning you can easily reference back otherdocuments in the sidebar. It’s missing internal links between documents like you’d expect there to be in softwaredocs, but you can always do a pass on those when it’s in its final form (that is, if it’s going to end up on the internet ina site).

If you write your whole documentation in one, broken-up page, you can use page jump anchors to help usersnavigate.

3/12

iA Writer costs $9.99 from the Mac App Store.

SimpleMDE (browser)

While you can technically write markdown in any text editor because it is a way to format plain text, not strictly a‘tool’, it won’t surprise you that it’s also possible in your browser! SimpleMDE is a both a functional markdown editorbuilt on JavaScript and an open source project to learn from and adapt for your own use, if necessary.

4/12

SimpleMDE is 100% free! Get the source on GitHub here.

reStructuredText editors

Markdown is one of the two most commonly used languages for writing software documentation, but there’s anotherwe’ve not looked at so far, and that’s reStructuredText. It’s very similar to markdown, but worth learning for softwaredocumentation purposes.

Docutils, the creator of reStructuredText, has put together a list of reStructuredText editors here, which includes:

The point of reStructuredText is that it’s easy to convert between different formats, especially from plain text to astatic website. See more info here.

Software documentation hosting options

It’s no good having just a bunch of text files living on your computer. They need to be accessible by developers andusers, which you’re most likely going to do by hosting the docs on the internet since it isn’t the 1980s.

Read The Docs

It’s remarkable that Read The Docs is free when you see all that it can do. Similar to GitHub, you can create asmuch open source material as you like that gets openly indexed on the site, but it’s going to cost you if you want tomake the docs private and internal to your company. For our purposes, it’s likely you’re going to be alright withhaving the docs readily available for users on the web.

5/12

The reason Read The Docs is so good is that you can effortlessly import documentation from any version controlsystem including Git, Mercurial, Subversion, and Bazaar. It also supports webhooks so the docs get builtautomatically whenever you commit code.

Check their Getting Started guide to get a feel for how it works and how your docs would behave when hosted there.

GitHub (& GitHub Pages)

If you’re using GitHub to manage version control for your software, you have, at the bare minimum, a README.MDfile in the repository. To use GitHub for documenting your software, like millions of others have done in the past, justfill that README in with markdown.

A great example is sferik’s t repository, screenshotted here:

6/12

If you want more than just one sheet of formatted text, you can take advantage of GitHub’s Pages tool (you get onefree webpage + hosting with each GitHub account, and you can even route a custom domain to it). Pages even hasgreat looking default themes that make your documentation look professional.

Above is atom.io documentation for Electron hosted on GitHub. It’s a smart choice because it automatically workswith GitHub’s version control, just like the rest of your software. See the site’s repository here.

Dropbox Paper (for internal use)

For internal software documentation use, Dropbox Paper is an excellent choice. Like its predecessor Hackpad, you

7/12

can use it to create a private wiki for employees. You can link documents together, insert code blocks, images andpage jumps, just as you’d demand from any documentation tool.

As you can see from the comments on the right, you can also use it to go through approval processes andcollaborate over the creation of documentation. Overall, it’s a great tool for internally developing and creatingdocumentation, perhaps with the view to publicize it later, or just keep it for internal use.

Process Street (for internal use)

For training new developers and keeping your documentation living all in the same place, Process Street is a solidchoice for software documentation. We use our own product for as much as possible, and since it’s a way to createand share structured documents, it lends itself perfectly to this purpose. Check it out:

8/12

It supports headings, text, video, image, and code blocks (to name a few), so if it can be documented it can bedocumented in Process Street.

Atlassian REST API Browser (for API use)

Atlassian’s REST API Browser (RAB) is included in JIRA Server, Confluence Server and Stash instances by default.It’s built for discovering APIs available for use in JIRA/Confluence environments, and also a place to host yourdocumentation. If, of course, your API fits the bill.

9/12

Document your API using this tool to give your JIRA/Confluence compatible API more exposure. Check here forAtlassian’s documentation on doing that.

Apiary (for API use)

As well as being a place where bees live, Apiary is a dedicated host for API documentation. Write in markdown, addmock API calls and Apiary collates that into something like you see below:

10/12

Anyone can test the API without having to go into the app or actually program a call, which makes it a superaccessible way to share your API, document it in-depth, and boast about what it can do.

Tools to automatically generate documentation from source code

There’s nothing like the human touch when it comes to documentation (it’s clear in the docs of Slack and Giphy, to

11/12

name a couple). However, as a starting point (especially for huge source libraries), it’s best to generate the skeletaldocumentation automatically. This work by analyzing the source’s functions and comments, and there are a fewdifferent options depending on language:

Doxygen (C, C++, C♯, D, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, Tcl, and VHDL)

GhostDoc (C#, Visual Basic, C++/CLI, JavaScript)

Javadoc (Java only)

Docurium (Ruby)

Before you go ahead and rely solely on automatic generation, I’d suggest reading this StackExchange thread whichweighs the pros and cons.

Final words on software documentation tools

There are plenty of fancy solutions, quick fixes and tools that are (quite honestly) almost identical. What matters inthe end is that you’re going to have to write comprehensive documentation and host it somewhere the user can getto it. Other than that, you’re free to use whatever makes your life easier. I hope you find your new favorite tool in this

list.

12/12