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.
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!
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.
In this article, we will explore the differences between XML and JSON. We will address which conditions best suit which format. At the end, we’ll dig into a few scenarios where XML will continue to play a crucial role in data exchange.
Documenting your code is important. It tells other developers what the code does, why it is constructed in a certain way, and how to use it. Good documentation saves them time when they are trying to perform a certain task that isn’t straightforward. It will probably also save you time because the human brain can only store so much information. Even your own code will confuse you at some point in the future.sp
Even though code documentation is important, many developers find it tedious. This is exacerbated by the fact that many companies associate code documentation with long Word documents that must be kept up to date manually. Not exactly developer heaven.
So how can we simplify code documentation while still keeping it effective? (more…)
Today we have made available compatibility update releases for GhostDoc and CodeIt.Right.
This update addresses the “Visual Studio still loading the project.” message and other issues after upgrading VS2017 to the v15.6.
Products updated include –
- GhostDoc v5.9 – all editions
- CodeIt.Right v3.3 – all editions
- GhostDoc Pro v2018 Beta
(Mar 9, 2018) Update: new build v2018.0.18070 has been posted to address the VS2017 v15.6 compatibility issue.
Changes in the Beta 3, build v2018.0.18030 –
- New feature – Document Project – now can generate XML Comment templates for a whole project
- Added support for the
<inheritdoc>tag – for type members only in the XML Comments as well as the generated help documentation. This allows using the tag instead of copying the documentation from base members and synchronizing the changes.
- Visual Editor improvements
- New commands – Add Table, Remove Table
- New commands – Add Note, Remove Note
- Now the tags not recognized by the Visual Editor are added back to the XML Comment when saving the edits
- Now render the Code Contract section preview
- A number of improvements that impact proper XML comment generation
- Added /cleanup switch for the command line tool – when used will delete all files and folders in the output directory before creating help documentation.
- Support for Code Contracts when generating help documentation
- Added Options -> General -> ‘Keep solution properties file in the .vs folder’ allowing to hide the solution properties file (<solution path>.GhostDoc.xml) in the solution’s .vs folder
- The Cleanup checkbox in the Build Help Documentation dialog has been changed to a button. Now the folder must be cleaned up manually – this is to prevent accidental file loss when the output folder picked at an incorrect location.
- Default toolbar icon is now Build Help Documentation where previously was Comment Preview
For the complete list of changes, see What’s New in GhostDoc v2018 Beta
For information on the original Beta release, please see the Visual Editing for XML Comments post.
Why do we have the tendency to comment out code instead of just deleting it? The reason is that we don’t want to lose a piece of code that might come in handy in the future. Maybe we think we’re still going to need it because it solves some problem in an elegant way. Or maybe it’s because it helps us when debugging.
It all boils down to fear of losing information. But commented out code will get in the way more than it will help you, and it’s better off being deleted. I’ll expand on why below and provide some possible alternatives.
Why Commented Out Code Is a Problem
1. It Distracts
At the very least, commented out code will distract you and your team members from the actual code. It’s tempting to think our brains can filter out the commented blocks or that just a few lines won’t make our minds wander. But in reality, the commented out code is just an extra hurdle your brain needs to jump when trying to make a mental model of what the code is doing. And that by itself is hard enough, even in very clean codebases.
2. It’s a Source of Code Rot
More often than not, commented out code will start to “rot.” The longer code stays commented out, the higher the chances it no longer fits when uncommented.
One possibility is that it just doesn’t compile anymore. The codebase will likely have changed, and the live code will have evolved with it. But the commented out code will still be as it was when you put it in comments.
A more dangerous situation could arise if the code does compile but the behavior of any underlying code is altered. The commented out code may make calls to other components whose behavior has changed. This means the commented out code no longer does exactly what it was intended to do. That’s a potentially be a dangerous problem, and it means you’ll be wasting your time trying to find the cause of an obscure bug. In both cases, it’s a risk to the team and the company, and one that could have been avoided.
Finally, the commented out code may have been a good idea at the time, but fast forward several months or years and you can probably come up with a better solution. Languages, frameworks, and techniques evolve, and in time you will have acquired more knowledge, causing you to solve a problem in a different way. Trust your future self to solve the problem that the commented out code solved.
So how can we avoid the problems caused by commented out code without losing our piece of code forever?
UPDATE: a fix for the VS slowdown when adding/renaming solution files included with the build 17335 on December 1, 2017
GhostDoc v5.8.17330 update is a maintenance update and includes
- Added SubMain.GhostDoc.Cmd.clr4.exe to run the command line utility on .NET FW 4.0
- Now can add XML Comments for single files outside of the project
- Now don’t run new version check when in Debug mode
- Updated styling for
- Improved scaling on high DPI monitors
- Issue documenting the Main method in the Community edition
- Issue with the conceptual content topic placement in the TOC
- Keep conceptual content tags in <solution>.GhostDoc.xml file in Pro, free version
- Added VB property parameters section in the Help file
- Visual Editing – removing exception row can now be undone
- Spelling literals with an ampersand character in Designer files
For the complete list of changes, please see What’s New in GhostDoc v5
For overview of the v5.0 features, visit Overview of GhostDoc v5.0 Features
Download the new build at http://submain.com/download/ghostdoc/
I remember the first time I encountered GhostDoc. It was an oasis in a professional desert of soul-sucking conformity.
Okay, wait. Let me back up and explain.
I was working in a custom app dev shop at the time. While working there, I worked on an assortment of apps, big and small, and I delivered to an assortment of clients, big and small. Some had their own internal maintenance devs, and some did not. And yet, in spite of this disjoint, hodgepodge arrangement, the company maintained a single and relatively involved coding standard for dozens of folks on dozens of projects.
The “Professional” Coding Standard
Most aspects of the standard were unremarkable and understandable. So, on the whole, this didn’t bother me. But there was an edict floating around in there that said every method and class, no matter what, needed XML doc comments.
This applied to code being maintained by client developers and to code that nobody would ever look at again. It applied to both API deliverables and to GUI crud apps that nobody would touch again. Why comment everything in this fashion, no matter what? Because it makes us “look professional,” that’s why.
And so I found myself laboriously going back and brainlessly adding comments to dozens of files. You see, I hadn’t known about this standard when I started, so I didn’t bother commenting this forms-over-data thing for which we weren’t even delivering source code. So I had a lot of “work” to do.
Initially, I contemplated writing my own commenting engine. I honestly think I could have done that in less time than it would take to hand comment. But then I figured something like this had to exist already, and my search led me quickly to GhostDoc.
Once I discovered that, I sprayed my code with comments like an exterminator taking care of an ant problem. Then I called it a day.
As I’ve discussed previously, this is NOT how I’d use GhostDoc today or how I’d approach commenting in general. But it got the “job” done, and the powers that be considered “my” comments completely acceptable. Project finished.
The subject of API documentation reveals a fascinating property of the software development industry that makes it truly unique. When you think of a product, you think of something polished and ready to ship. That’s true of software and also of the broader world in general. But only in software can you crack the product open to reveal its internals and then ship that as well, with a different purpose.
When you expose an API, this is exactly what you do. Take an offering like, say, the iconic Trello. On the surface, you have a lightweight kanban utility with a nice user experience. But you also have an underlying platform for developers to use. Through the Trello API, developers can build their own functionality to extend and enhance the offering, creating a win for everyone. Developers win because they can do cool things. Trello wins because it generates more interest in their offering. End users win because they have a richer set of functionality at their disposal.
Of course, extensible software is hardly new. But these days, it’s becoming more and more the norm. And it’s also something that companies plan for from the get-go, rather than scrambling to bolt on at a later date. So it’s important to treat APIs as first-class citizens, conceiving of them as actual products and doing things like, say, shipping API documentation.
What is API Documentation?
Most people reading can probably infer what this means, but it’s worth being explicit before proceeding. API documentation is a standalone set of deliverables that you offer to clients of an API. And for the sake of thoroughness, “API” stands for “application programmer interface.” So you’re documenting how programmers should interact with your platform through code.
At a bare minimum, your API documentation should include information about setting up to use the API. It should also describe the different function calls, parameters, and return values. Sophisticated API documentation will also include examples, caveats, gotchas, and any other useful tidbits that might make life easier for developers.
Is API Documentation Really Necessary?
Could you ship your product and API with no documentation? Sure. Could this work out for you? Probably, somewhere, somehow. But I wouldn’t call it a good idea in most cases.
The entire point of an API is to open up your product for extension. You invite developers to come in, poke around, and get comfortable. You want them to use your product, extend it, and build a community around it.
Without API documentation, you’re not really rolling out the welcome mat. Instead, you’re leaving it up to them to learn by trial and error what to do. The probable result? They’ll try, get frustrated, and leave. Or perhaps they won’t try at all, viewing it as a waste of time. Either way, they’ll go looking for your competitors who, presumably, have nice API documentation.
So let’s assume that, all things being equal, API documentation is desirable. What are some strategies that shops have for their API documentation?
API Documentation Via Oral Tradition
While not doing any documentation is technically a strategy of sorts, I won’t cover it here. Instead, I’ll talk about what, with tongue planted in cheek, I’m calling “oral tradition.” This looks similar to the “we don’t bother” strategy of documentation in that it doesn’t produce documentation artifacts. But there is a strategic difference.
What I’m driving at here is a decision to support API users via a form of hand-holding. You’re not publishing documentation that you ship alongside the API, but you do make the effort. Instead of giving them docs, you actually talk them through it or, potentially, work on it with them. You might supplement this with ad-hoc communication, such as emailing them an example.
If you work on a product like Trello, this sounds insane. But consider that not all APIs have equal constituencies. Perhaps you don’t generally support an API at all, but you’ve opened up some of your code to a major B2B client for integration. In this case, it’s so custom and specific that creating documentation makes no sense.
Using MS Word or Something Similar
Let’s move past the case of highly specific APIs for custom partners and into the realm of broader, more general consumption. When you throw your API open to the public or to any arbitrary paying customer, you need something tangible.
One tried-and-true way of doing this is to write user manuals in some form or another. This has roots going all the way back to man pages, and probably beyond that. Whatever the particulars, you put your API documentation into some digitally or physically distributable format. MS Word is a common choice, given its ubiquity and formatting capabilities.
But whatever you choose, the mechanics are the same. A developer or technical writer goes through the API and, well, writes about it. This generally includes everything I mentioned under “what is API documentation” and probably more. After all, it tends to have the feel of writing a book, naturally lending itself to verbosity.
This is a well-worn path to pleasing your users, and it has a lot of merits. The main downside, however, is that it’s extremely labor intensive.
Automated Documentation From the Outside In
Since historical methods for generating API documentation proved so labor intensive, it should come as no surprise that people used automation to relieve this pain. While you certainly can fire up MS Word and write all about your API, you no longer need to start from scratch like that. Tooling has caught up.
The first tooling approach that I’ll mention, I think of as outside-in API documentation. You build your API as you normally would, exposing the functions and means of interaction. Then you point a tool at your API’s surface. The tool parses it exhaustively and generates initial documentation based on its findings. From there, you mark it up as you see fit.
Swagger offers an example of this. You build a REST endpoint that you expose. Swagger takes that contract as input and generates your initial API documentation from there.
Automated Documentation From the Inside Out
Now let’s consider a complementary approach. If you think of outside-in API documentation as black box, we’re now talking about its white box counterpart.
Here’s how this works in concept. Given the source code for an application with an API, you use that source code to produce the API documentation. This happens by inferring various properties of the API — member visibility, parameter and return types, exceptions generated, application behavior, and even code comments.
In fact, code comments can be an excellent means for this style of API documentation. GhostDoc works this way. Assuming that developers tend to create well-formed method header comments anyway, it uses those as the basis for generating help documentation. You thus kill two birds with one stone: commenting the code for maintenance purposes while generating documentation for API consumers. Developers never need to open MS Word (or whatever).
What Strategies Do You Have?
My intent here was to broadly cover some options and to offer heuristic advice. Having done the former, let me do the latter. Whatever you choose, you should automate it as much as you possibly can. This helps you cut down on your labor and save time and money. You should also pick something idiomatic to the techs you’re working with. If you’re in the business of REST endpoints, Swagger is great. If you’re building .NET tools, GhostDoc will be a huge help. You need to figure out what best suits your purposes.
But all that being said, there’s no way I’ve covered every possible approach to API documentation in this post. So, what are some of the things that you do? How do you handle accommodating consumers of your API? Weigh in in the comments!