{"id":484,"date":"2012-11-20T20:34:12","date_gmt":"2012-11-21T01:34:12","guid":{"rendered":"https:\/\/www.goer.org\/wordpress\/user_comments_in_documentation_stop_it_stop_it"},"modified":"2013-11-17T06:01:09","modified_gmt":"2013-11-17T06:01:09","slug":"user_comments_in_documentation_stop_it_stop_it","status":"publish","type":"post","link":"https:\/\/www.goer.org\/Journal\/2012\/11\/user_comments_in_documentation_stop_it_stop_it.html","title":{"rendered":"User Comments in Documentation: Stop It. Stop. It!"},"content":{"rendered":"<p><iframe loading=\"lazy\" src=\"http:\/\/www.youtube.com\/embed\/Ow0lr63y4Mw?rel=0\" height=\"315\" width=\"420\" allowfullscreen=\"\" frameborder=\"0\"><\/iframe><\/p>\n<p>Today I took a look at <a href=\"http:\/\/webplatform.org\">WebPlatform.org<\/a>, which (among other things) reminded me that man oh man, do I hate user comments in documentation.<\/p>\n<p>If you want an example of how user comments degrade perfectly good documentation &#8212; well, there are many, but the most obvious one is <a href=\"http:\/\/php.net\">PHP.net<\/a>. 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&#8217;s use of redirects (typing php.net\/functionname &#8220;just works&#8221;) is absolutely brilliant.<\/p>\n<p>But if you scroll down to comments on any given page, you&#8217;ll see bad practices that should have died years ago, code that doesn&#8217;t do what the user thinks it does, people complaining about (imagined) bugs, and worse.<\/p>\n<h2>Wait, but people really like documentation comments.<\/h2>\n<p>It&#8217;s true that when you ask developers what they <em>like<\/em> 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&#8217;s the community contributing to the documentation. Who doesn&#8217;t like community? Yay community!<\/p>\n<p>Comments make people <em>feel<\/em> good. But comments are also just about the worst way possible to collect and incorporate feedback.<\/p>\n<p>The key problem is that for documentation, comments are <em>part of the product.<\/em> It&#8217;s as if you built a web app by building the datastore, adding application logic, tuning the user interface&#8230; and then allowing any random user to modify the navigation bar any way they like for all other users.<\/p>\n<h2>Oh, I see. So you&#8217;re saying you hate the community and kittens?<\/h2>\n<p>No. What I am saying is that contributing feedback is a <em>solved problem<\/em> 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.<\/p>\n<h2>That&#8217;s setting the bar too high. We want feedback from a wide range of users.<\/h2>\n<p>Respectfully, if someone is writing technical documentation for software developers, and they haven&#8217;t grasped the basics of version control, they should not be allowed to directly contribute changes to your documentation. Period.<\/p>\n<p>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:<\/p>\n<ul>\n<li>Issue trackers<\/li>\n<li>Email<\/li>\n<li>Wikis<\/li>\n<li>IRC<\/li>\n<li>Social media<\/li>\n<li>Meetups<\/li>\n<li>&#8230;<\/li>\n<\/ul>\n<p>Again, collecting feedback from users of all knowledge levels is a solved problem. Tools exist for this. Some of them are even pretty good!<\/p>\n<p>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.<\/p>\n<p>Well, okay, I can imagine quite a bit.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Respectfully, if someone is writing technical documentation for software developers, and they haven&#8217;t grasped the basics of version control, they should not be allowed to directly contribute changes to your documentation. Period.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-484","post","type-post","status-publish","format-standard","hentry","category-tech"],"_links":{"self":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts\/484","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/comments?post=484"}],"version-history":[{"count":2,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts\/484\/revisions"}],"predecessor-version":[{"id":565,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts\/484\/revisions\/565"}],"wp:attachment":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/media?parent=484"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/categories?post=484"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/tags?post=484"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}