Make Unity Documentation PUBLIC COMMENT SECTION

Unity Documentation suffers from multitude of problems, and solving them all at once is unrealistic. However, allowing users to have per page Comment Section as a platform
will solve majority of issues with missing documentation information,
users will add comments with instructions/workarounds additional info, caveats
and so on.

Please vote for this feature https://feedback.unity3d.com/suggestions/add-comment-section

So the proposed solution to Unity Team is to

Have a public comment section per page on unity docs where users share info directly with each other avoiding bureaucracy and long wait times.
Additional issues with reporting system is that the decision making of what to actually include, the cherry picking can never be sufficiently precise, because of amount of various scenarios and issues that each page can generate that no human being can know 100% of, thus always leaving some vital for someone information out.

a good example
http://www.wowhead.com/item=109626/gorgrond-flytrap-ichor#comments

some minor random item from the game and a guy left a comment with useful information without anyone asking him ahead - direct output of what he found, he SHARES info, he doesn't wait for someone to ask about it, and its HIGHLY UNLIKELY that he and the one who needs that info will ever cross their paths on any forums due to lack of discoverability.

http://www.wowhead.com/item=72235/silkweed#comments
another example with a lot of comments, they dont wait for anyone to ask anything, they just share their findings, this format is objectively superior, its direct info sharing, condensed and on point.


1. Have a public forum account linked to Comment section
1a. Comments have karma, thus self regulate
Karma should not propagate and is a property of one single post only and doesnt benefit author(i.e. does not accumulate on his account) thus allowing people to focus on doc issues and not on inflating ego.
1b. Comments have tag with Version of unity they were written for
1c. Comments can be flagged as disruptive and picked up by unity Doc team.


PROS:

• Quick way to find solution to most common issues people have
• Ability to share small tips and tricks
• Fast compared to traditional issues reporting
• Does not require a lot of attention from Unity Team

CONS:

• Rating system may be abused (proposed system should be per post only and not have any accumulation of any karma or post counters of any sorts anywhere)
• Should be separated visually (i.e. in another tab) because some people don't like mixing of social and solid documentation.

Other proposed ideas:

• Youtube video embedding, to share YT tutorials.

This will solve majority of issues with missing documentation information,
users will add comments with instructions/workarounds additional info, caveats
and so on.

For successful examples of such systems :

http://www.wowhead.com/item=72235/silkweed#comments
https://msdn.microsoft.com/en-us/library/windows/desktop/ms687280(v=vs.85).aspx
http://php.net/manual/en/doc.changelog.php


Official Unity Doc team response

Spoiler: Read

As an alternative idea would be to have additional Hub like Answers, but without questions, where people could directly share Advices, and have the doc pages have a link to search Advice Hub based with query based of currently opened Doc page.
This will be even less work for unity team, and still benefit people in same way - direct, quick access to relevant information.

This thread raised a lot of hate towards this proposal to which im tired to respond with the same over and over again:

You are not forced to use it. You are not even affected by that additional tab. Assumption that somehow just the existence of that button affects you in any way, is just stating that your "dislike" of it is actually not real if you are not able to control yourself enough to not open the tab with comments. Again because you are personally not able to control where you click, other people who will benefit greatly from it should suffer?

 

Which pages would you say are crude and contain 'weak one liner' documentation? Have you reported them to our Docs team? Could you list them here?

 

--sorry for the rude part!--

Anyways ill throw some of my latest moments i had with it (and i work with unity for 4 years already)

http://docs.unity3d.com/ScriptReference/UI.Slider.html
Set() method marked as public and protected, that does not reflect reality

http://docs.unity3d.com/Manual/MultiSceneEditing.html

this is plain misleading and wrong because the scenesetup class contains properties instead of fields for some reason and cant be serialized and i suspect it is not marked as Serializeable in the first place

https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager.SetActiveScene.html
Here example of crude one liner that doesnt reflect half the problem you will have with it



Was it added to doc? No. Not a finger was moved to make documentation more inclusive of actual real issues you will get and more people are stepping in the same hole and making more threads.

--sorry for the rude part!--
And no its not my job to monitor documentation and send you reports all the time, but i would be happy to occasionally add my experience to help other people.

 

I'm not sure if I agree on public editing even for select community members but I would at least like see the report issue link in the documentation that has been asked for ages ago. Using bug reporter for documentation issues always felt very clumsy... but at least we have had the forum section for documentation for a while now. Still the report link would be best as you could report it immediately while on the page and not distracted to report it elsewhere.

Documentation could use a community member notes section in each page with up/down voting and all tied to Unity account (similar to php documentation).¨

 

All right, and what would you say if we had a comment section where comments have karma as usual, and they are tagged with version of unity they were written for.

For such example you can look at wowhead

http://www.wowhead.com/class=11/druid#comments

They have their wiki page, tabs with data/statistics and a tab with comments.

These comments are n1 source for all actual real world usable tips and additional info that was missed by automated wiki population system. When i had issue with WoW and could not locate something all i had to do is go to comments and near the top i would find exact instructions on how to achieve it because a lot of people had the same issue.

You see how actually simple it is to make efficient public doc?

 

I'm all for anything that is realistically possibly to do and simple commenting with up/down down voting should be fairly trivial job for even an intern. However sadly tags, karma etc. seem to be impossible task for the current web development team that is either overloaded with work or has no members assigned full time. I haven't seen or noticed major improvements in the documentation section in terms of usability past few years.

 

No need to be hostile! I wouldn't be asking you these questions and talking to you on a Sunday evening if we didn't want your feedback. And of course we want to improve the documentation!

Did you report these using the bug-report system to flag up documentation issues? Its there for that very purpose! There are many many many forums and threads that our docs team can't be reading every single forum post that is made.

Im not making you look like a fool?! Not sure why you would get that impression! And of course its not your job, but you have raised this thread in an effort to help improve docs quality. In fact, we are hiring more Technical Documentation Writers! https://unity3d.com/jobs/position?id=132911

 

Im afraid that no matter how much people with strong english skills you hire, it wont solve the problem, because im afraid to get to the level when you actually understand the underlying codebase and per object issues, you have to work few years with the engine solving in depth specific issues.
That is why bruteforce hiring more people is a wrong way to solve fundamental problem, and also money sink.

Allowing people to comment on page as described above would cost you some money to set up the system, and would actually help by order of magnitude better.

 

We aren't brute-force hiring; but we are aiming to bring in more awesome in-house technical C# writers to help improve the documentation.

I don't work on the documentation team; but in my honest opinion I don't think a completely publicly editable official documentation system would really be the best approach to instructing a piece of software.
Who vets all of the public posts? How do you know if something written is reliable or not? What if some of the documentation is forgotten by the original contributor and becomes outdated? What stops trolls tweaking and modifying things to disturb other users?

IMO, a neat system would be to perhaps have a 'flagging' button, on each docs page, that would highlight a change needed to be made or information to be added; as opposed to opening the Editor and submitting a bug report (Which is the current recommended way of doing that) Ive messaged the documentation team if such a thing already exists.

 

Can you check the link to wowhead provided above and look yourself?

The idea is not to have editable pages but a comment section per page with self moderating commends with karma.
This will self regulate the system, just as it does on the whole rest of the internet(StackOverflow is built around it) even on your Unity Answers.

Then the doc team could just monitor reported comments for whatever "trolling" there is.

 

Updated op post to reflect current state of proposal

 

The MSDN documentation is probably what many people are familiar with. It has a link at the bottom of each page and has a question.

Was this page helpful? (yes or no)

If you click the No button it provides optional feedback box where you can type in 1500 characters on what you think needs to be improved.

Here is a MSDN where you can see such an example. (scroll to the bottom of the page)

https://msdn.microsoft.com/en-us/library/windows/desktop/ms687280(v=vs.85).aspx

 

Thats an excellent example! Ive forwarded it to the Documentation Team as a suggestion.

 

Community will judge if the other used posted stuff is valid and valuable. This works pretty well pretty much everywhere where they have similar system. If a user has to use his Unity account to post then he could be easily blocked from documentation section in case violations by moderators or after getting poor karma below set threshold. Unity already has some level of account/cross system synergy so you could for starters allow all Pro users, answers section people with x points/votes or forum users with x post to leave public documentation comments.

 

I don't know why unity is afraid of such system. I am really confused this is the most USER BENEFICIAL system, that avoids waiting for someone. Yet

you are endorsing again same concept of "reporting" to unity, and it appears to me you are trying to avoid involving community, even at the cost of effectiveness.
You see im thinking solely about myself, i think what is the best way for me as a user to get and give info?
And comment section is the n1 fastest and most diverse way to deliver information, i don't want someone at unity to cherry pick what should and should not go into the documentation, because it was proven numerous times that its a faulty error prone approach. The community is self regulating, people will share numerous ways to solve same issue and you are YET AGAIN emphasizing a rigid not flexible approach.

 

Hmmm, I don't think Community judgement would really work for official documentation. It works for Unity Answers as that tends to be question revolving on more specific topics (Right down to the user's code). I personally believe a software's Official Documentation should be created and regulated from the source of the software; as opposed to the greater public who range in all different skills and understandings of the software.

 

Just as i predicted, you are hindering the effectiveness of the system with your assumptions.
We provide you examples of working systems that are built around community regulation, you are still standing on the side of poorly working, outdated system that everyone knows is flawed, and your defense is that you "dont think" it will work.
That is not an argument, provide examples of where such system fails.
Also explain how "range in all different skills and understandings of the software"
Is bad to end user. Because to me it doesn't make sense. Anyone can help and everyone can contribute and when system is "karma" based the most professional and inclusive comments will be always on top.
AND nobody forces you to read them. Everyone satisfied.

 

Could you give an example of a widely used piece of authoring software (Millions of monthly users) that has it's official documentation entirely created and regulated by the community/public? And is of a high and stable quality? And hasn't been tampered by trolls? Im genuinely curious and would like to be enlightened!

 

I'm not talking about documentation itself but community notes that are addition to the actual page. People can post examples or additional notes and tips. For example see the php documentation for explode function: http://php.net/manual/en/function.explode.php

edit: As you can see there are several examples, tips and warnings and most useful ones voted to top. Inaccurate or bad ones are voted down and dimmed at the bottom where as some systems auto hide these after set threshold.

 

At this point i think you are derailing this thread on purpose. It was repeated numerous time to you that we are proposing comment section, yet you are saying

Like, what? Why are you doing this?

 

Im not derailing?! You are making many accusations! Im just trying to have a conversation and understand your suggestions.

So a comment section to accompany each docs page?
Who would write the main body of the docs page; The public/community or the software-developer?

 

Do whatever you want with the actual page content, the community needs comment section to add all the TON of missing info tips/tricks/advices/warnings/etc etc etc.

 

But we already have a system for submitting this ton of missing information; for it to then be validated by our Documentation Team.

 

Nice. Just nice. I dunno if you literally dont see a benefit in what im proposing that is literally best way to handle this issue. Like if you really dont see the benefit i just don't know. I have nothing more to add i just give up, whatever.

pretty sure its highly effective. Whatever man, you want to stay in this stone age state your doc is right now - go for it.

Just dont say stuff like this ok.

 

Okay Andy. Here goes: the Devs write the main body, and you get a comment section along with that for the users to play around. If it is karma based it will be self regulating and this system is proven to work. And from time to time the devs may actually look at the documentation pages and maybe incorporate the most useful comments. That a win win situation. It makes everything faster, more reliable (crowd control). It is cheap for you guys because you literally get the answers that people want for free, and no one has to wait for anybody.

 

I don't know how are you still missing it when 2 people have clearly written it that Unity should be responsible of the documentation itself as it requires certain level of knowledge . That's why pointcache said earlier that hiring new documentation writers wont help the key issue when they do not have the knowledge and have to fish it from various places.

Comment/community section is there to fill the gaps the documentation team might have missed or are not aware of if they are not developers that work with the engine.

 

On some of the MSDN pages they do have a community additions button where users can add public comments at the bottom of the article. Not makes any changes to the original article.

On the same MSDN page I have given previously you can see this has two comments at the bottom of the article under Community Additions.

https://msdn.microsoft.com/en-us/library/windows/desktop/ms687280(v=vs.85).aspx

If Unity wants to implement this feature I think the best benefit would be to restrict it by license level (e.g. only Unity Pro Users)

 

and to be honest. you seem to be missing the point all thread long. like for real. every single post the same point gets made and you keep missing it. All that they are proposing is a frickin comment page. for comments. self regulating. self regulating = no trolls. = trolls get reported. = commmunity QA.
you can do whatever you want with the actual documentation that has been said multiple times. If you decide to not add anything fine, the community helps each other in the comments. so whats the downside? explain it please. I am really trying to see your point.

 

Absolutely agree on user comments for doc material

offline docs obviously would come without the page feedback.. but like php docs .. having a comment section for each docpage is an invaluable resource of useful information to do with that particular feature/function, known quirks, workarounds, bugs!, and just all round good stuff to know like an extra toolbox of scripts and functions that others have built around such features.

http://php.net/manual/en/doc.changelog.php

if only unity docs could be half as good as php docs and its framework (anyone know if there framework for docs/user commenting/page bug reporting is available to use? its seems really similar to a wiki setup
.

 

+1 to the community section to each and every separate documentation / help item

the only thing i'm not sure of is what would happen when the refrigerator reseller hits it

 

Possibly community moderators like in answers (they would only moderate comments, not actual docs of course).

 

Woah, loads of people posting! its awesome that we have passionate people about this subject.
Although, its a bit tricky for me to reply to all of you individually before many, many more posts appear!

Just for a disclaimer: I do not worked on the Documentation Team and I am merely having a discussion in this thread based on my own personal interest and thoughts.

Would the role of the comments section be to eventually roll into the main body of documentation? It seems like comments of:

would imply that actually having this information in the main body would help improve the documentation page about the topic; as opposed to existing separately in the comments section. In which case, we do already have a system in place for submitting bug reports for documentation pages (Through the Bug Reporter).

 

If in doubt, you really can't go wrong by first allowing only pro users and long time Unity answers/forums members to post in the section. When all has worked well for a while you could open the flood gates and pretty much allow anyone with an Unity account to post there.

 

Andy...again. The comment section is a place for people to gather and work stuff out that is not in the main body. If after 1000 months or any other time period the documentation team stumbles across the comment section and find stuff that is ultra useful they may put it in the main body ... or just leave it as is. All that matters is that it is there, somewhere.

 

Yet you are Unity representative so everyone speaks to you as to UNITY team, expecting our input to propagate somewhere.

Its up to you. Ok following your logic, what is the point of your reporting (that very few use probably) if you have a comment system with karma.

Why would anyone report anything. Makes no sense, one system is rigid and not transparent, doesnt involve discussion, is solely judged by person on your end without assurance he understands the issue, and so on,
other system is based of judgement of users that actually work with the engine full time, solving complex problems and have direct knowledge of issues and they need a platform to share.

 

But again your back to the bureaucracy where everything takes forever or nothing happens which is the original point of this thread. If user X submits a documentation issue with the clumsy bug reporter it gets in queue and some doc writer might pick it weeks or months later and then use several weeks to find out if the info is good to add from engine devs. All this for one documentation entry. User X gets frustrated and never submits another documentation issue again.

Community section is not a replacement for the documentation but it supplements it.

 

I think theres a decent idea hidden behind this very rude post, you'd hope game developers would be more forgiving of a few oversights, given the fact that they have to put up with it being pointed out in their work constantly.

However, back on the topic, I think it could work if it was just under the actual documentation, not to replace it but just so the community could add some helpful tips and so on.

 

im sorry if im rude, its not about the actual oversights, its about denial that the profound problem exists and that report system is clearly inefficient.

In my opinion would be best to have ether a tab, or sliding from right panel with comments, because some doc pages are really long.

 

IMO, I'd prefer if docs would just be made a wiki, editable to anyone with Unity account. This way they could be adjusted as needed by the community (with oversight by current doc team to rollback any troll pages and so on).

 

I genuinely dont believe anyone is denying theres a problem, I'm sure you understand that its important to find out what the problem is realistically and what the best way is to solve it before just going in and implementing a new feature. Its good of you to apologise though.

Oh actually that could work quite well. Either way, I dont think the comments should become the documentation, though I dont think you're saying that, just an addon to them.
On this note, without trying to feature creep, a way to add user-made tutorials to parts of the documentation, in the form of youtube videos, would be very helpful.

 

One Raid and the party is over, just sayin

 

The issue with that and why its implausible is because that will force unity team to monitor each page and patrol for trolls and so on, basically its inefficient from maintainability point of view, however comment section is decoupled so it doesnt need such attention from Unity Staff

 

I don't see why bug reports (if reported from a specific docpage, couldn't somewhere on that docpage link to the reported issues, like linked to the bug/issue tracker) its more readily available info to see that this function or something on the docpage maybe having bugs on unity version x

its transparency and allows for more upto date info to been more readily found, I don't bother looking at bug tracker issues, I do look at docpages, and when I've had certain functions not behaving correctly, its much more logical to go looking at that script reference for that function and go from their in reporting issues that are specifically seem to be happening via that function.. not so easy to bother going to look at the issue tracker for similar issues, and of course reporting problems on the forum I don't think will ever go away, but docpage sure needs some work.. even a changelog and last user comment history for the docpages would help for those who just like to keep tabs on the current climate on unity features/issues

the issue/feedback tracker page layout completely sucks, its layout is the worst I've ever seen a for any sort of bug tracker, as I've said before it looks like it was designed for mobiles and for people who might briefly look at it for 5mins at lunch break.. its useless number of results per page, fat padding everywhere poor use of screenspace.

 

As well as that, it could actually discourage the unity team from adding more features. More features means more docs, more docs would mean more to patrol, more to patrol might mean hiring more staff, suddenly adding some cool new feature becomes very expensive.
So yeh, I'm not sure about making it a wiki

 

Numbered for convenience.

1. Existing doc team, then when it is known that user isn't a troll, he or she gets vet-free access e.g. their posts doesn't have to be accepted.
2. By trying it in the editor in the way documentation explains it.
3. Some other person takes over when he or she sees outdated info
4. Existing doc team is part of wiki administration and as such they can rollback any troll changes and ban repeat offenders. Another part is trusted contributors.

Wikipedia model works and it works great.

 

another slightly less but still 'bureaucracial' option for this are community pull requests against doc repo, but the selfregulatory section would suit for this probably the best - it reflects changes and current state of affairs much faster than any other approval need system
and time / the actual message - update roundtrip is one of the main concerns here

 

Open wiki sites are easily vandalized and even in case you missed it back then the UnifyWiki which is now under Unity domain was often spammed and messed up. The point was here to have a system to supplement the documentation without the need of Unity employees to babysit actions daily. All they have to do is to add the comment area for us and karma/votes will keep it in check. It could be limited to select group first that have accounts matching certain criteria.

 

How many people are there on Unity documentation team?

 

another issue which might be somewhat addressable with this is ''issue localization'' - right now there's no single authoritative place dealing with a given single topic reflecting current internets )
online help system is accessible even from within IDE, for additional information it's necessary to either search & filter forum noise and / or do the same on answers

it's a good idea overall although i'm not entirely sure about how exactly should be implemented - there's definitely not small amount of work involved

 

Thanks @Andy Touch for taking time out of your weekend to correspond here. Sorry you got hit with bombastic replies.

I think the MSDN model proposed above is the best way to go. It keeps a closed content model while still allowing the community to add content through moderation.

I for one, is 100% against a wiki documentation. I don't want to have to look into who wrote what and check their post history to check if they know what they're talking about. For official documentation, I want it directly from Unity and only from Unity. We can't compare this to Wikipedia, as reputable sources are a lot harder to find about an astronomically small element of a specific engine. It simply isn't feasible for a game engine. I only want user content to be on official Unity documentation if a Unity employee has checked it's truthfulness.

Moderating user suggested content would be the perfect role for a new hire as they would be exposed to a large array of the Unity environment and can reach developer resources for help.