Today I took a look at WebPlatform.org, which (among other things) reminded me that man oh man, do I hate user comments in documentation.

If you want an example of how user comments degrade perfectly good documentation — well, there are many, but the most obvious one is PHP.net. PHP is a monster of a language, but thankfully PHP also has been blessed with a longtime dedicated documentation team that has built up a substantial and highly useful set of user guides and API reference documentation. The core documentation is solid, and the site’s use of redirects (typing php.net/functionname “just works”) is absolutely brilliant.

But if you scroll down to comments on any given page, you’ll see bad practices that should have died years ago, code that doesn’t do what the user thinks it does, people complaining about (imagined) bugs, and worse.

Wait, but people really like documentation comments.

It’s true that when you ask developers what they like about the PHP documentation, they often cite the comments. Engineers often decide that comments are a need-to-have feature for documentation sites. After all, it’s the community contributing to the documentation. Who doesn’t like community? Yay community!

Comments make people feel good. But comments are also just about the worst way possible to collect and incorporate feedback.

The key problem is that for documentation, comments are part of the product. It’s as if you built a web app by building the datastore, adding application logic, tuning the user interface… and then allowing any random user to modify the navigation bar any way they like for all other users.

Oh, I see. So you’re saying you hate the community and kittens?

No. What I am saying is that contributing feedback is a solved problem in software development. Make a goddamned pull request! Or send a patch. Or whatever you do normally. Treat your documentation source the same way you treat source code.

That’s setting the bar too high. We want feedback from a wide range of users.

Respectfully, if someone is writing technical documentation for software developers, and they haven’t grasped the basics of version control, they should not be allowed to directly contribute changes to your documentation. Period.

That said, feedback from less experienced users is still valuable. If someone notices something is wrong, or wants to add an example, or needs to point out a section that is confusing, there are plenty of ways to collect that feedback. These include:

• Issue trackers
• Email
• Wikis
• IRC
• Social media
• Meetups
• …

Again, collecting feedback from users of all knowledge levels is a solved problem. Tools exist for this. Some of them are even pretty good!

In any case, please stop inventing new commenting systems and gluing them into your documentation sites. You are taking what should be a relatively straightforward generated/static site and turning it into a dynamic CRUD site for no good reason. A more colossal waste of engineering time I cannot imagine.

Well, okay, I can imagine quite a bit.