Documentation is an important aspect of any application. Even though that no one reads it and most of the times it remains a daunting task for developers to document the code, there are still a number of documentation tools that can be used in order to automate the process.
Word documentation is rather straightforward. Every class, function, and global variable is documented thoroughly with a place to attach screenshots or sample code. On the other hand, code documentation is substantially easier and more intricate than its word counterpart.
It’s a big question that’s been around for decades. There are many different aspects to consider when choosing the best documentation tools for visual studio, development, information architecture and technical writing. The tools listed here will encompass all of these needs. We’ll dive into each tool and why it can be beneficial to you.
Documenting code is an essential part of development. Using code comments and other techniques, software documentation helps developers to understand existing code and remember the purpose of complicated sections when changing or adding functionality to a project. This article introduces a range of tools for .NET developers who prefer Visual Studio as their programming environment. As well as explaining how to use the tools it contains a brief evaluation of each option, describing its features and limitations, with references to primary sources such as documentation, tutorials and video.
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
- You can’t 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.
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
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:
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.
Document360
Document360 is a software documentation tool that gives you complete 360 support for your project documentation. You can create rich documentation with ease using features such as the Markdown & WYSIWYG editor for efficient and structured writing. Other notable features include an uncompromised authoring experience, a rich theme, built-in analytics, enterprise-grade backup & restore, versioning capabilities, and so on.
With simple configuration features, you can manage various project documentation, configure numerous users, and examine analytics to help you maintain your knowledge base content fresh and relevant. It offers robust security like IP Restriction, Custom Domain Mapping, Enterprise SSO, Cookie Consent etc.
You can also integrate with a variety of third-party helpdesk, chatbot, and CRO technologies, such as Zendesk, Intercom, Hotjar and Zapier. As a result, it is appropriate development software for all business sizes
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.
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:
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.
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.
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)
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 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.
Haroopad
Haroopad, by HarooPress, is a highly-visual document processor for technical and development teams.
The charm of Haroopad is in its simplicity. As stated on the team’s website, “Markdown is simple, but has…portability and extensibility. The goal of the Haroopad is also simple: To be a web friendly document editing tool.”
Still, Haroopad manages to deliver the functionality and customizability we’ve come to expect from these open-source solutions.
Haroopad Features
- Themes, skins, and customizable UI components
- Import files from YouTube, Twitter, Vimeo, Slideshare, Flickr, Instagram, and more
- Export documents to Workpress, convert to PDF/HTML
Haroopad Pricing
- Haroopad is completely open-source.
Helpjuice
Helpjuice’s knowledge base software is an all-in-one solution for your team’s knowledge management needs — software documentation processes included.
With Helpjuice, teams can create, publish, and deliver helpful software documentation to internal users, and to the customer. On the user’s end, Helpjuice presents this documentation through an intuitive, user-friendly interface — allowing for maximum browsability and digestibility of information.
Overall, Helpjuice allows you to develop software documentation with the end-user in mind.
In some cases, this may mean diving deep into technical explanations and information. In others, it may mean delivering technical information in a more simplified, comprehensible manner.
Either way, using Helpjuice to create a knowledge base will ensure you can create and share great documentation with the relevant stakeholders.
Helpjuice Features
- Limitless authoring, formatting, and editing of text and multimedia content
- Templates for streamlined knowledge creation and organization
- Advanced search functionality makes finding the right document a cinch
- Permissions ensure individuals only have access to the necessary areas of your knowledge base
- Integrations allow content to flow freely from your knowledge base to other tools and platforms
Helpjuice Pricing
Regardless of pricing tier, all Helpjuice users get access to all of the tool’s features.
- For 4 users: $120/mo
- For 16 users: $200/mo
- For 60 users: $289/mo
- For unlimited users: $369/mo
Whatfix
Whatfix is a Digital Adoption Platform that allows you to create step-by-step walkthroughs that act as real-time software documentation by guiding employees through your software. If you already have a knowledge base, you can display your documentation in a self-help widget.
Whatfix is redefining how software documentation is displayed and consumed, with new content embedded directly within your software applications in forms such as interactive guidance, contextual walkthroughs, self-help FAQs, popup notifications and beacons, and more. The platform also allows you to measure the usage and effectiveness of your documentation with user analytics.
10 features of good software documentation tools
It’s easier to create various types of software documentation — for various types of software — when you have the right tool. Good documentation can even make a product better over time. Look for tools with these features:
1. Markdown and HTML support. Software documentation tools that support both markdown and HTML are preferable. Markdown is a common standard for software documentation; it’s essentially a plain-text, abbreviated form of HTML, which can be too wordy and awkward to use to write manuals. Markdown generally works for writers who want HTML-like text modifiers to make lists, tables and more. Also, Markdown imposes limitations; you cannot change fonts or put borders around objects, for example. So, the ability to mix HTML and markdown is helpful.
2. Feedback. Feedback makes software better, and documentation tools have various options to collect and review feedback. Everyday product users will discover features you never thought of — I’ve had users contribute entire code examples. These users will help uncover errors in your site and ask clarifying questions. Some tools connect software users and developers over email, or with a question button for comments. ReadMe, a popular documentation tool, lets users check out pages and make changes to them. Those changes are then put into a queue for developers to approve, reject or merge with other changes.
3. Custom, cloud-hosted domains. There’s no need to host your own product documentation. For example, with ReadMe, start with a domain like your-product.readme.io. Then, when you are ready to publish the domain, change the path to documentation.yourcompany.com and add a DNS record to point it to ReadMe.
4. Access control. You won’t have a single writer contributing all documentation on most software builds. Writers from different roles and levels add information, so look for a tool that provides access management.
5. Click-button APIs. Make it easy for your users. Your choice of tool should enable users to click a button to run APIs directly from the documentation.
6. Client-side backups. Software documentation tools should let you create your own backups. Don’t depend on someone else to back up your system.
7. Technical support. Some tool vendors provide meager support. Find a vendor that will respond when you get corruption in a page or that can help you to recover something that is lost. ReadMe gets a low grade in this respect, at least with developer accounts; ReadMe Enterprise might offer better support.
8. Customizable landing pages. Ideally, a software documentation tool will let you use both HTML and style sheets on landing pages.
9. Table of contents. Documentation tools should enable you to set a clear table of contents for easy navigation.
10. Publishing control. You should be able to publish and unpublish pages as needed.
Conclusion
Code documentation is an essential part of developing applications. However, the process of writing proper documentation can be quite complex and tiresome for developers. Fortunately for us, there are a number of tools available to make this process easier.
If you are a developer, one of the first things that you have to do is take note of your development environment. This has always been the primary reason why a lot of developers are reluctant to host their code on GitHub because they want to make sure that their development work spaces can stay private. Even if you host the code on your own server, it is essential that you understand the documentation tools used for it properly so that other developers and even clients will be able to navigate through it easily.