Documentation

It’s a sad fact that code documentation rarely gets the attention it deserves. That’s a shame since it’s often a crucial part of the final product. Bad documentation often makes the difference between how easy it is to fix a bug a year later or whether a customer chooses to integrate with or buy your software.

Many software teams say they don’t have the time or resources to do documentation. I recommend integrating it with the process, but I’ve seen this go wrong way too many times. Erik Dietrich describes projects that required XML doc comments for every single method and class. I was on a project where every story in Jira required corresponding documentation. The developers reluctantly wrote a lot of documentation that we believed no one would ever use. And we were right.

With documentation, it’s key you have a well-developed documentation process. And you should also take advantage of modern tools to save time and identify documentation gaps.

Plan As a Product

Documentation IS a product, even if it’s only used internally. Once you see it as a product, treat it like you do your other products. At the bare minimum, you want to have a collection of use cases to measure the success of the final product. Who is your audience? How will the documentation be used? What information do users need to successfully do these things?

Integrate With Code

Once you have a vision, you should consider tools that save time and prevent duplication of work. No one wants to have to write code and then go into some other system to write documentation. It doesn’t help that the other system is usually a mediocre wiki or content management system.

In 2018, there’s no reason to do this. Modern documentation automation products like GhostDoc save time and help with consistency. GhostDoc can generate code comments automatically from within Visual Studio. With GhostDoc Pro, you can use these to generate help files.

Develop an Editorial Workflow

I know, you’re skeptical of automated comments. You’ve probably seen some pretty baffling documentation that was so obviously autogenerated. That’s why I recommend it as a tool, not as a substitute for a good process.

It’s critical that you have an editorial process as well. Would you push unreviewed code to production? Then why push unreviewed documentation? On my teams, I have documentation go through peer review just like any code does.

GhostDoc has some awesome features for editorial review. You can easily mark and track comments that are auto-generated. That allows reviewers of any kind to find and evaluate them. In my experience, many are good enough, but there are still many that need some additional explanation.

No one likes outdated documentation that doesn’t work. GhostDoc can find documentation comments that are out of sync with the parameters, return types, and type parameters of the associated code.

Review at a High Level

But peer review isn’t enough to evaluate the software overall, and it’s not enough for documentation. Documentation should also be reviewed as a whole. I recommend doing this as a team by having other key stakeholders involved as well.

I also recommend having other non-engineers review documentation. How many developers complain that marketing doesn’t “understand their product”? Well here’s an opportunity to finally write something that helps. The best documentation is usable on some level to marketing, product, project, and sales teams.

Analyze Usage

Many companies do user research for their software. If your documentation is user-facing, consider doing some user research on it. At Write the Docs Portland this year, Jen Lambourne gave a great talk about how their company does user interviews for documentation. She said, “It’s a way to find what works rather than just what’s popular for us.” In the end, you’ll also gain key insights about your product beyond just documentation. Many teams use this research to develop new features, drive marketing, and identify product weaknesses.

Many teams also use traditional user analytics tools like Google Analytics or Pendo. This allows them to capture data on how users find and use documentation.

If the documentation is internal, you still want to have some basic user research. For this, I often do what I call “cross-training.” When I was a (not very) competitive swimmer, we sometimes did cross-training. It was where swimmers would do non-swimming dry-land exercises like running and weightlifting. This increased our flexibility and strength in ways that swimming alone couldn’t.

Use your documentation as a cross-training tool. Have one team review another’s documentation. This reduces the bias toward writing documentation that is too difficult for non-experts. It also builds organizational capacity—now you have more developers in your organization who know your software well.

Support Documentation Organization-Wide

Documentation users and writers are EVERYWHERE in software organizations. Many companies now have practices and working groups for developer tools, culture, and architecture. Why not have one for documentation?

This kind of support signals that you believe documentation is important. It also helps bring together experts to develop best practices and share knowledge. I’ve been in more than one of these groups where people didn’t even know each other before. They didn’t know anyone else in the company did documentation!

The Takeaway

Bad, incomplete, and absent documentation, whether user-facing or internal, is a risk. Great documentation is an asset. If you’re not thinking about documentation, you’re behind.

Take the sting out of documentation by developing a modern documentation process. That means automating what you can, then reviewing it as a whole to see whether or not it makes sense and is useful. And when the documentation is “done,” analyze usage and keep improving it.

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.