18 Software Documentation Tools that Do The Hard Work For You

18 Software Documentation Tools that Do The Hard Work For You process.st/software-documentation August 4, 2020

Benjamin Brandall August 4, 2020 Document Management, Software, Writing

✅ Bonus material: Git Workflow Checklist to simplify & streamline version management Without documentation, software is just a black box. And black boxes aren’t anywhere near as useful as they could be 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 it 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/16

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

To explain software documentation in more detail, we will cover the following topics in this Process Street post: Let’s get started.

What is software documentation?

“Documentation in software engineering is the umbrella term that encompasses all written documents and materials dealing with a software product’s development and use” – Prototype.io, Software Documentation Types and Best Practices All pieces of software should have some form of documentation that explains, in detail, what the product is, how it works, and why it works that way.

“If it isn’t documented, it doesn’t exist” – Sitepoint, A Guide to Writing Your First Software Documentation As a developer, your main aim is to write the best code you possibly can. You want your code to be best in class, easy to read, easy to use, and you want great things to happen as a result of it. Right?

But without documenting what you’ve done and why you’ve done it: No one else can use your code but you Without documentation, it’ll be incredibly difficult, nigh-on impossible, for someone else to pick up your code and work on it. They might even scrap it and 2/16

start again, as, in some cases that would be quicker than trying to work out what you’ve done and why you’ve done it.

You can’t update or improve it Can you remember what you ate for dinner on Saturday, three months ago?

Unless you’re a complete creature of habit, chances are you can’t. So it’s fair to say you probably won’t remember what code you wrote and why you wrote it, two, three, four months after you wrote it. If you can’t remember the reasons behind your coding decisions, then you will struggle to be able to update or improve it.

Despite this, software documentation is a task that gets rushed, is often done badly, and sometimes gets deprioritized or even forgotten about.

Before we start talking about what tools you can use to write software documentation, we need to think of a way to make sure the task gets done in the first place.

This is where Process Street can help.

Process Street is a piece of business process management (BPM) software that can be used to create, manage, and follow processes.

More about what Process Street is later, for now, let me show you how you can use it as a tool to help you fit software documentation into every software development project you work on.

Below is an example of a pre-made Development Process template. This template was created to help software engineers and programmers build and deploy their software in the best way possible.

Click here to access the Development Process!

To get this template, either log in and add it to your dashboard, or sign up for a free trial.

This template is a perfect example of a process that you can follow every time you want to build and deploy a new or updated piece of code.

It has clear steps that will guide you through the whole process, from creating a branch to work in, to putting your changes live. These steps will make sure nothing gets missed and that the entire process goes smoothly, every single time.

We’ve designed this template to be used as a guide to help you create a development process that works for you. Every company is different, every software project is different, and every development process is different.

You can edit this process and add in the tasks that are relevant to you, your company, and your project.

3/16

Which brings me back to software documentation. You could add ‘software documentation’ as a task into this development process, or any other process you create. That way, anyone working through it will be reminded and encouraged to complete it, as part of the process.

I’ve got a few more premade process templates that might be of use to you, which I’ll include at the end of this post.

Before we get to that, let’s look at where you can store your software documentation.

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 and users, which you’re most likely going to do by hosting the docs on the internet since it isn’t the 1980s.

Use Process Street to document any recurring process

Source

For training new developers and keeping your documentation living all in the same place, Process Street is a solid choice for software documentation.

First, you could create a process for writing your documentation, to make sure you capture all the right details and make it as useful as possible.

Then, using the following easy-to-use features, you can write up and store your documentation in one single place: Image widgets Text widgets Video widgets 4/16

File widgets Subtasks Email widgets Embed widgets Creating and storing all your recurring software documentation within Process Street means it can be accessed by everyone in the company. You can share it with others, send it for approval, set reminders to review it, and update it easily.

It’s simple to set-up and even easier to use. Here’s a sneaky look at one of our checklists in action:

If something can be documented, it can be documented in Process Street.

Sign up for a free trial here and see for yourself.

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 as much open-source material as you like that gets openly indexed on the site, but it’s going to cost you if you want to make the docs private and internal to your company. For our purposes, it’s likely you’re going to be alright with having the docs readily available for users on the web.

5/16

The reason Read The Docs is so good is that you can effortlessly import documentation from any version control system including Git, Mercurial, Subversion, and Bazaar. It also supports webhooks so the docs get built automatically 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.MD file in the repository. To use GitHub for documenting your software, like millions of others have done in the past, just fill that README in with markdown.

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

6/16

If you want more than just one sheet of formatted text, you can take advantage of GitHub’s Pages tool (you get one free webpage + hosting with each GitHub account, and you can even route a custom domain to it). Pages even has great 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 works with 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 can use it to create a private wiki for employees. You can link documents together, insert code blocks, images and page jumps, just as you’d demand from any documentation tool.

7/16

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

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 your documentation. If, of course, your API fits the bill.

8/16

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

Tettra (for internal use)

Source

Tettra is a kind of knowledge base software where you can document your development, or anything at all.

We use Tettra internally at Process Street for a bunch of use cases. Day to day, I use Tettra to have a single place where all my processes are documented so that I never 9/16

forget how one relates to another or how the various automations we’ve built have been set up.

Tettra is great if you’re looking to create a library of sorts. This means it’s brilliant for software documentation or even just as an internal wiki for your company.

Given that Tettra is specifically designed for knowledge management, it comes with a host of other supporting features too. For example, it can make suggestions as to what extra content or sections you might want to add to give a more complete picture of your org and how things fit together.

You can see a little video here for how a dev team might look to use Tettra: How Product & Engineering Teams Use Tettra.

Or, you can go here to read about how we use Tettra alongside Process Street: Automating Workflows and Checklists: Process Street Case Study .

Check it out!

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

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

10/16

We’ve discussed where to store your software documentation, now it’s time to look at how to write it.

Writing tools for software documentation Software documentation is often written in markdown to allow for hyperlinks and formatting while keeping it plain text so it can live alongside the code files in version control. That means that a lot of my choices for writing tools are simple markdown editors that make the writing experience enjoyable. Additionally, there are also a couple of very effective 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 popular markdown editor for Windows. It’s optimized for blog posts, websites, articles, READMEs, and, of course, software documentation.

11/16

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 other documents in the sidebar. It’s missing internal links between documents like you’d expect there to be in software docs, 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 in a site).

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

12/16

iA Writer costs $9.99 from the Mac App Store.

ProProfs Knowledge Base ProProfs Knowledge Base is a fantastic little tool for all stages of document creation; from writing and editing, to customizing, setting workflows, and publishing. You can add multimedia, import existing content from word docs, PDF, or PPTs, save multiple versions of the document, and restore them when required.

Source

13/16

But the real beauty of this tool lies in its useability. Anyone and everyone can use it to write software documentation. Whether you’ve been documenting software for years or have only recently started, it’s an incredibly simple and easy to use tool.

ProProfs is free to use, or you can upgrade to the premium package which is $112 per month.

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 editor built on JavaScript and an open-source project to learn from and adapt for your own use, if necessary.

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 another we’ve not looked at so far, and that’s reStructuredText. It’s very similar to markdown, but worth learning for software documentation purposes.

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

14/16

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

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 name a couple). However, as a starting point (especially for huge source libraries), it’s best to generate the skeletal documentation automatically.

This work by analyzing the source’s functions and comments, and there are a few different options depending on language: Before you go ahead and rely solely on automatic generation, I’d suggest reading this StackExchange thread which weighs the pros and cons.

Final words on software documentation There are plenty of fancy solutions, quick fixes and tools that are (quite honestly) almost identical.

What matters most, in the end, is that: a) you write software documentation for every piece of software you build b) you write it comprehensively and host it somewhere that the user can access I mentioned earlier that I had a few more development process templates that you might be keen to check out?

Well, here they are…

Process Street development process templates Before I give you these templates, let me explain what Process Street is a bit more.

So we know Process Street is super-powered checklists. It’s a piece of software that will help you create and manage processes.

But, there’s more to Process Street than just that. Watch this intro video to find out what I mean: Not only can you create a process template, and run individual checklists from this template every time you need to complete the process, but you can customize it using these extra features: You can assign tasks, get approval, enforce an order that the tasks need to be completed in, and connect your workflow to thousands of apps via Zapier, webhooks, or API integration.

Watch this webinar on our newest features to see how you can get the most out of them: 15/16

So, with all this in mind, take a look at the below, premade templates: Network Security Audit Checklist This template can be used by a risk manager or equivalent IT professional to assess a network for security vulnerabilities.

Click here to access the Network Security Audit Checklist!

Software Deployment Template Use this checklist for each piece of software you deploy, so you can ensure a consistently solid approach to updating and fixing the products you work so hard on.

Click here to access the Software Deployment Template!

Monthly Website Maintenance Checklist Use this monthly website maintenance checklist to optimize your site’s loading speed, scan for vulnerabilities, and review your search visibility.

Click here to access the Monthly Website Maintenance Checklist!

Software Testing Tutorial This process can be used to finely comb through individual sections of your code, before submitting them to your software deployment.

Click here to access the Software Testing Tutorial!

And there you have it.

You’re now free to use whatever makes your life easier. I hope you find your new favorite tool in this list.

16/16