This post is a response to this forum posting by a Unity employee on why they are not going to have comments on documentation pages. That thread was locked, so I've posted my response here instead.
I wrote this because I think this stuff is really important. The documentation is not just "incomplete"; it is often out-of-date, misleading, and downright incorrect. The approach of throwing more people at the documentation team is completely missing the point: there is too much for you to document.
And, since our work forms part of the 'public face' of the company, we have to make sure that the content we produce - the grammar and language we use, the clarity and voice of the text, the screenshots, the layout and order of the pages, etc - all have to be consistent, and up to a certain quality which requires a process of writing, editing, proofing for english, proofing for technical correctness, and publishing.
The comment system would not be replacing the documentation, it would be supplementing it. Look at all the work you just said you have to do for any documentation, and it's no wonder the docs aren't as thorough as they need to be.
To be clear, I'm not saying the documentation team isn't working fast enough; I'm saying you're trying to do something impossible.
However the scale of the job is kind of hidden from view. There are actually around 12,000 individual pages in each edition of the Documentation. We also have about 300 developers who are continuously adding new features and improving existing ones - which need to be documented."
This is exactly why you can't possibly handle it as the documentation team alone. With a comment system, every single one of those 300 developers could add comments to the documentation pages for features they've added. Their comments would give much needed insight, without having to go through the complex proofing process that the docs team has to go through.
First, I personally don't think we should have public visible comments on the doc pages. The problem with this is that they either have to be moderated or unmoderated. Moderation takes a lot of time - it would basically be at least one person's full-time job.
If the comments on docs become so popular that it becomes someone's full-time job to moderate them, that is a GOOD thing, not a bad thing. I'm highly skeptical the comments would ever get near that volume, but that is definitely not a problem. I think 99% of bad stuff would be caught by user moderation (ex: upvotes/downvotes, "flag as spam", "flag as incorrect", etc).
To see why this comment stuff is important, you've got to look at what people are doing right now to learn how to do stuff in Unity.
Here's an example that happened to me a few days ago:
-
I decided to code something in Unity using Rigidbody.angularVelocity
-
I type "rigidbody.angularvelocity" into Google and the Unity Documentation is the first result.
-
I read the Unity docs and all it says is "The angular velocity vector of the rigidbody."
-
I still don't have enough information to go on, because I don't know whether the velocity is per-fixed-update or per-second or even whether it's in degrees or radians.
-
So I go BACK to google and try to find some other page that tells me more about angularVelocity, so I find some Unity Forum link or maybe a Unity Answers link.
-
I end up skimming through many pages of Answers/Forum posts until finally someone offhand mentions that it is "radians per second"
Do you see the problem here? It's that the important information is completely disconnected from where it is needed! Those posts about angularVelocity should be on the angularVelocity documentation page. That page should be a centralized resource for all things about angularVelocity. A single one-line comment from a user would have easily saved me an hour of searching (and saved hundreds of hours for the hundreds of other Unity users with the same problem).
Now your response might be "we have to fix the angularVelocity page then", but again, that is missing the point. There is no possible way that the 5 members of the docs team can have as much spare time or Unity experience as the thousands of Unity users (nevermind the hundreds of non-docs Unity employees).
Now the other argument is "what if the posted information is wrong?". Well how is that any different from if I go find the info on Unity Answers and it happens to be wrong? A disclaimer of "this is not official Unity-provided information" and a simple upvote/downvote system will alleviate most of those problems. If I find a comment on the docs that is wrong, then I'll downvote it and I'll reply with a comment saying "Hey, this answer is incorrect, here's the actual answer:". Now anyone seeing the docs will see both of our comments and have a better idea of what the right answer is.
Why does this sound familiar? Because it's the exact system you already have with Unity Answers, and it works well!
To put this another way: if a user encounters missing info in the documentation, their next action isn't going to be "I guess I'll just wait until the documentation team updates this page with more information". Their response is going to be "I guess I'll go to Unity Answers". The commenting system is just simplifying that process for them; it puts everything in a centralized, authoritative location.
You guys know you have tons of smart, helpful users. Trust them. Let them help you to make the docs better.
Please seriously consider this.
Thanks,
-Matt
Hi, it's Ben here (from the Unity docs team). Thanks for the thoughtful and well-written response. Can't promise anything, but I'm just writing to let you know we haven't ruled anything out, and I'll definitely bring this up in our weekly team meeting this monday coming.