More than a decade ago, I worked somewhere that would ship CDs containing commercial software. ?Along with others, I’d program applications that ran commercial mail sorting machines and provided a user interface for the operators. ?To update or patch the software, we’d cut official CDs and send them out in the mail.
These CDs would, obviously, contain the software. ?But they’d also contain a rather elaborate PDF of the user’s manual. ?In some cases, we might mail them a physical user’s manual. ?And that manual was a formidable, polished document.
You’re probably expecting me to complain about writing that document. ?But I won’t do that because I never had a hand in writing it at all. ?Back then, we had a professional tech writer on staff that handled all manuals and end user documentation. ?At most, I would interact with this person when he’d shoot me the occasional email, asking how something worked.
If you were to ask me about documentation tools back then, I’d have looked at you strangely. ?I dunno. ?Ask the tech writer.
Documentation Tools Today Run the Gamut
Today we have a much different landscape. ?Between the rise of agile methodologies, ease of software delivery, cost savings, and automation, I suspect very few organizations hire tech writers to draw up user manuals for their products. ?That’s probably gone the way of the installation CD.
And today you probably have to help out when it comes to documentation. ?That means you need to leverage some documentation tools — at least if you want to avoid serious boredom.
Also complicating matters is the fact that modern documentation takes many forms and has many audiences. ?Gone are the days of only CD user manuals and man pages. ?So I’ll talk today about documentation tools, but I’ll divide the discussion up by audience and purpose.
User Manuals for Products
Let’s ease in with the scenario I talked about already: user manuals. ?In this case, you put together easily readable information aimed at non-technical users. ?This doesn’t dominate the landscape the way it once did, but it certainly still applies, particularly with B2B and desktop software.
You might consider not overthinking things. ?Microsoft Word has been helping people produce nicely formatted documents for a long, long time. ?Or, if you prefer not to spend the money, you could go with Google Docs, a free alternative.
You might go a different authoring route if you prefer markdown formats. ?MarkdownPad?and StackEdit?offer this capability, among others. ?Really, the main thing you’ll probably want is the ability to generate PDFs for distributing and printing. ?And with print-to-PDF functionality and a nice ecosystem of conversion tools, you can really let design and editing preference guide you for end user manuals.
Release Notes (Internal or External)
It may not spring to mind immediately, but release notes also constitute documentation. ?Most commonly, they represent abridged versions of full-blown documentation, detailing in bullet form what has changed in the latest edition.
You might issue two different flavors of release notes: release notes intended for public consumption and internal release notes. ?You usually publish the former on your website, whereas the latter includes internal, more sensitive information.
But in either case, you’ll use similar sorts of tooling. ?To make this as easy as possible on yourself, look to your project management/ALM tooling. ?For example, both JIRA?and Github offer this sort of functionality. ?Whatever you use probably also does, or else you can adapt some plugin to help you do it.
Comments in Code
Now, let’s switch gears a bit and move away from worrying about end users. ?Not all documentation happens with non-techies in mind.
First in this category, consider the humble code comment. ?If you’ve thought the only way to handle this is typing every keystroke by hand, you have other options. ?At the very least, I hope you’re aware of XML doc comments, which allow you to write comments that can be used by other applications. ?IntelliSense is an example.
But you can go way beyond that with a documentation tool called GhostDoc. ?GhostDoc will allow you to generate method and class comments automatically and then adjust the result. ?This saves a lot of keystrokes. ?But you can also manage comments, as the tool can detect ones that get out of sync with the methods and classes they describe.
Developer Guides for Language Library APIs
Speaking of GhostDoc, let’s talk about another use case for the tool. ?In the world of end users, you want nice, easy-to-read documents. ?But what about the case where you have developers as your users? ?They still want manuals, so to speak, but those manuals look a lot different. ?They have descriptions of source code, APIs, and examples.
Using GhostDoc, you can take your code comments and turn them into nice-looking documentation for your programmer-users. ?They’ll see listings of classes, methods, and arguments, including descriptions and exceptions possibly thrown. ?You can add examples and even custom content to the documentation as well. ?If you distribute source code to other programmers in the form of an API or a library, this is indispensable. ?You can generate and distribute the documentation as a file or serve it on a website.
Developer Guides for Web Services and SaaS Products
While we’re on the subject of websites, what about a different kind of API with a different kind of user? ?Forget, for the moment, about the relatively tight relationship between producers and consumers of OOP code and libraries. ?Let’s consider developers exposing APIs as web services.
As with a tool like GhostDoc, you still want to automate as much of the documentation as you can from the API. ?You just have to go about it a bit differently. ?I suggest that you use a tool like Apiary?or Swagger?to help automatically document and even design your API. ?In 2017, there’s no need for you to hand-document your WSDL or REST endpoint. ?You can just point tools at it and have templated documentation ready for your tweaking or distribution.
Collaboration Utilities Among the Dev Team
The last use case I’ll mention has a unique intended audience compared to the rest here. ?I’m talking about you and other members of your team.
Hopefully you’re automating as much as you can, but are you documenting the rest to make life easy? ?Do you have somewhere that you’ve captured your team’s standards, build process documentation, domain knowledge, and the like? ?This counts in the realm of documentation tools because these are things you’re documenting for yourself, other team members, and possible future newbies.
For something like this, you can always use a shared drive and some Word documents, but that gets messy fast. ?I’ve never been much of a Sharepoint fan, either, though you can certainly use it to this end, as well as Google drive. ?I’ve personally always had more luck with tools like MediaWiki,?Basecamp, or Confluence. ?But I wouldn’t get too caught up in which approach you use, just as long as you pick one and actually use it. ?I can’t tell you how much productivity I’ve seen lost to team knowledge existing only in people’s heads.
Documentation Tools Matter
I might apply that same reasoning more broadly. ?You can (and should) weigh the merits of different tools, but using the tools vs not using them is a much wider gulf. ?The world has come a long way since I wrote code for a CD and some tech writer explained it in a PDF.
In today’s world, you probably won’t have the luxury of a tech writer. ?But, at the same time, you’ll have a user base that will ignore your product if you don’t make it discoverable and easy to use, you need to provide documentation to help them. ?You’re getting pinched in the middle, and documentation tools offer your only path to satisfying both constraints.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
1 Comment. Leave new
[…] SubMain, I wrote a post taking you through different documentation tool options that programmers have.? User manuals, release notes, and all the traditional stuff, but then also new approaches that […]