Search Unity

  1. Megacity Metro Demo now available. Download now.
    Dismiss Notice
  2. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

Make Unity Documentation PUBLIC COMMENT SECTION

Discussion in 'General Discussion' started by pointcache, Apr 3, 2016.

Thread Status:
Not open for further replies.
  1. r618

    r618

    Joined:
    Jan 19, 2009
    Posts:
    1,303
    ( besides UT used to run the answers on SO licensed backend and they abandoned it so they probably won't get into similar waters any time soon ;)
     
  2. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,350
    r618 and Ostwind like this.
  3. orionburcham

    orionburcham

    Joined:
    Jan 31, 2010
    Posts:
    488
    Hi! I think I fully understand the OP's suggestion, and genuinely like aspects of it. However, even my favorite ideas must be able to survive heavy scrutiny. So here are a few ways I would imagine a public comment system on the official Docs might go wrong. How might we address these?

    (Btw- please don't imagine there's any hostility or judgement coming from my end in this post. There's really not- honest. :) )

    1. Dozens of people post valuable comments on 'Page A'. Hundreds benefit from some detail that was missed in the documentation. Then, the API changes slightly- some other function which affects this community-submitted detail. Now, none of the official documentation on Page A is incorrect, but 20% of the community comments suddenly are.

    How long does it take for this to get sorted out? Does someone go in and remove the now-incorrect community information? Who? Would we end up with cases where newer comments have to read "Don't listen to older comments- things have changed."? What happens when, multiple Unity versions later, things have subtly changed three times? Which "things have changed" comments do new users know to listen to?

    2. Those lonely one-line documentation pages are a bummer to run into, and they often affect the least-used features of the engine. If I were to run into one, then see that a single, kind soul had commented with more information, I would be stoked! But what if that one guy was totally wrong? How would I know? Self-regulation only works if many, knowledgeable people are active on a page.

    A few positive things I do think have come to light in this article:

    1. Users don't know that you can report documentation issues through the bug reporter. Having a very visible way to request more info, directly from a doc page, sounds like it could increase visibility here (this is totally separate from a comments system idea).

    2. People are often unaware that UT doesn't like their employees to comment on the forums using a separate 'non-work' account. This creates issues in which unrelated Unity employees are yelled at for voicing their personal opinions, because posters think "finally! Someone who can make things happen!". That's understandable. I wish people were more familiar with this company approach.

    3. It sounds like there's something to the idea of the community filling in the gaps of lacking documentation. However, some people really like the idea that the documentation is a known-quantity. Sparse or not, you can normally rely on the documentation not to provide wrong information. And if it does, the reasons are easier to predict (it got missed in an API change, for example). One thing I almost never have to worry about the official documentation is how legitimate it is. Do I have to question the source of this info? No- it's 100% from the company behind the code, UT.

    A comments section could hinder some of these comfortable assumptions. If we were to add a comments system, I would hope it would meet several design requirements:
    • Adding information to fill in the blanks
    • Never introduce hostility, regardless of the number of users involved
    • Avoid adding confusion caused by out of date information
    • Avoid adding conflicting information that would require further detective work by the user
    • Be a tool for supporting the official docs, not overtaking them
    I think if we could design a system that meets all those requirements, we'd be on our way to a powerful commenting feature.
     
    Last edited: Apr 4, 2016
    jwinn, pk_Holzbaum and landon912 like this.
  4. Ostwind

    Ostwind

    Joined:
    Mar 22, 2011
    Posts:
    2,804
    The section is for community notes so some kind of viewer discretion is always there as posts have date when they have been added. The old info just goes away as time passes and people down vote on it, this is how it usually works. In some places people who maintain the documentation might remove some deprecated info while updating a page but usually this is not needed.

    Everyone with an Unity account has the ability vote but adding notes could be limited to accounts matching certain criteria. The section is not for questions, chatting or for debates (see example page below).

    PHP manual is one of the good examples where is has worked well for several years, example:

    http://php.net/manual/en/function.explode.php

    ..and adding a note to the function:

    http://php.net/manual/add-note.php?sect=function.explode
     
  5. orionburcham

    orionburcham

    Joined:
    Jan 31, 2010
    Posts:
    488
    those PHP docs are a great example! Great to see a community where this has been working/we can talk about specific examples.

    Not that this negates that point, but the example of a top voted comment on that function page is:

    "If eval() is the answer, you're almost certainly asking the wrong question."

    This is a good example of something I would really not want to see on the Unity Docs site. I go there looking for straight, unopinionated answers. This is not an unopinionated answer. :/

    How could our system avoid this?
     
    Last edited: Apr 4, 2016
  6. Ostwind

    Ostwind

    Joined:
    Mar 22, 2011
    Posts:
    2,804
    It's a bit confusing but the eval() is generic example of the voting system and how the notes will evolve and shown every time no matter which function you are adding notes :)

    (if you refresh the page you can see it replayed)
     
  7. ziegel999

    ziegel999

    Joined:
    Aug 22, 2014
    Posts:
    6
    Okay I think at this point it is obvious that @neginfinity is just trolling or something. No way this b****** you are dropping here is for real. 1. A comment section will literally not change ANYTHING. It is one small button. One effin button. No one forces you to look at it. No one forces you to interact with it in any way. Do you click Malware Ads because they appear on your screen? Do you ? I think you dont.
    At this point you are just trying to derail the thread and it is obvious. If you are sincerely stating that the mere EXISTENCE of this section (that you wont even see if you dont enter it) will change anything for you then this is some religious stuff going on in here.
    A PER POST karma based system is tbh the best solution for crowd intelligence gathered information. There cant be any "gangs" or some other crap happening because there simply is no global counter. Also, it is really funny when people with legit addons to the support capabilites of Unity are getting attacked for that. Its like Person A wants another (or better) kind of support ( in this case the dev team doesnt even have to do anything apart from adding that feature) and you are saying "Well duh, the support is okay already. For its size it is okay!". With this reason you might aswell stop support and expanding the documentation right at this point dude. Having such a huge product means support takes a lot of ressources. Its called being customer friendly. It is 2016. By now people like you should have realized that having strong ties to the community and open idea sharing and helping each other is the best way to go with such a large product. It benefits everyone.

    So how about we go back on topic and stop derailing. Would be cool. Me for example I am rather new to Unity. I figure out stuff on my own but a lot of times I have to resort to googling for specific functionalities that are just not documented or their uses are not properly shown. Also with a comment section, as mentioned, you have very VERY specific cases that are being solved by someone and then posted there so people that might have this exact specific need dont need to waste time and go forum diving forever.
     
    Last edited: Apr 4, 2016
  8. ziegel999

    ziegel999

    Joined:
    Aug 22, 2014
    Posts:
    6
    @orionburcham you are right with the thing about regulation based on userbase. It can only work properly if a lot of people use it. However, if a person says something in there and it is wrong, no one forces you to take that as the only (false in this case) solution and you may move on.
    The question is. Does it do more harm to have a few wrong answers (to questions that exist anyways and are not answered in any way) or is it more beneficial to actually have a few decent answers among them that otherwise would drown in the forest of dead forum posts.
     
    Last edited: Apr 4, 2016
  9. Yukichu

    Yukichu

    Joined:
    Apr 2, 2013
    Posts:
    420
    I personally do not want a comments section. I want to read the documentation. If I want more information, I find it somewhere else. I don't want to sift through all the comments/replies to make sure there isn't something I missed. The documentation should document what a method/object/whatever does. It shouldn't have 'best practices' or 'if you overlap the bounds of this UI object with another it will increase draw calls by 2'. That stuff goes somewhere else, like the forums/wiki.

    MSDN yes/no question where you can submit suggested improvements sounds decent. I like it. I find it tedious to open Unity to file a bug report for website documentation.

    I also would like to point out that with the accusations and attitude of many of the posts here would just make me ignore this whole thread completely. It's made for good soap opera lunch reading.
     
    neginfinity likes this.
  10. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    I think the main issue with this is that it would be like reading a user manual where everyone has scribbled in the margins. Sure, you don't have to read the margins but it's distracting and an inefficient way of storing information.

    The crucial issue that I agree with @pointcache on is that there needs to be a way for people to readily make information available to others at the time that they solve a problem. Sometimes we figure things out and want to help out all the people who have been looking for a solution, and the only way is necroing three-year-old unanswered questions or posting a question with an accompanying answer (not sure if it would even get past the mod queue). So something needs to be fixed there.

    The thing is, the answers section is precisely for users interacting with one another to solve shared problems - so a system is already basically in place for what is required, although I agree it needs improvements. But rather than trying to improve the old system, which works well in a lot of respects, some of the people here seem to be dismissing it altogether and ranting against whoever disagrees.

    It was pretty ridiculous to see someone get a UT member on the thread, something which we all wish we could do on a whim, and annoy the hell out of them until they disappeared. I don't know where you're all living but even in the 'corporate world' things only get done when you know how to deal with people.
     
    Yukichu and neginfinity like this.
  11. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
  12. frosted

    frosted

    Joined:
    Jan 17, 2014
    Posts:
    4,044
    Sockpuppet ahoy.

    I vote no on the comments. User generated commentary is garbage 9/10 of the time. Better to have less information than incorrect information.

    Especially in an environment like Unity where you have loads of non programmers or newbie programmers. No thanks. Perhaps you could make a special forum with a thread for each doc page (I believe ngui did something like this) and you can have active discussion and feedback there. You could add a link from the manual page to the forum page so it's easy to open up.

    But keep it separate. Make docs authoritative and correct.
     
    MV10 and zombiegorilla like this.
  13. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    To all the haters -
    Assumption that the feature that you are not even forced to use has to be excluded because you don't like it, is
    extremely selfish. You are helping nobody you are just standing in the way of other people who need this.
    Again you are all irrational - NOBODY FORCES YOU TO EVEN OPEN COMMENTS and you still are AGAINST
    it. Im personally amazed you are programmers with this logic.

    Im done/out.
    Actually no, im here for those who need it.
     
    Last edited: Apr 4, 2016
    darkhog likes this.
  14. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    Nobody's hating, and nobody's out to get your idea. Is this the first time you've been to a forum?

    You still haven't said anything about why it wouldn't be better to do a few little improvements on the existing system - Unity Answers?

    Unity have limited resources and people, so it makes sense for each person to argue for what they think is most effective. I think Unity Answers could be improved and I think it would be a waste of time and effort on their part to implement a whole new system just so you can have it on the same page. I agree with the 'tip' idea but no reason why it can't be implemented on the existing framework.
     
    frosted likes this.
  15. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    I agree that if you redesign the Answers to be "advices" it would be great!
    HOWEVER the majority of criticism comes from the fact that they don't want to see ANY changes on doc pages as in not even links, which kills the purpose, of having quick direct access to advice section.
    If doc pages were linked to some "Advice hub" so that when you press on Doc page "Search advices" it would perform search in that advice database with the current open Doc page title query, it would be amazing in my opinion.
    But again, the criticism that i receive is irrational and based of that "we just don't like links in our doc pages, QQ"
     
    darkhog likes this.
  16. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    358
    Hi, I'm from the Docs team.

    We currently have five people on the team - two are new hires who started just last month. We're actively trying to hire more, and with this expansion we have big plans for ramping up on the quality and quantity of the docs over the coming months.

    When viewing the docs from the outside, 'solving the issues' by - for example adding a comments section - can seem like a trivial task, and it can be confusing as to why parts of the documentation seem to be lacking or incomplete. 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. We currently have three separate versions of the manual on the go (two public versions: 5.3, 5.4b and the 'next' version internally). 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.

    Regarding the proposal of a comments/feedback section - we've had discussions about things like this internally, it's something that comes up regularly. We actually did have a public feedback submission form on the docs a while back, but it didn't last long - part of the problem was that it was simply a freeform text submission field. This meant every submission needed to be read, understood and acted on individually by someone here. As well as there being tons of duplicates, there was lots of 'bad quality' feedback where it was either vague, or suggestions/improvements that we didn't have time to process. We would of course have to check every suggestions/improvement for accuracy, before adding it to the docs!

    We are in the middle of deciding how best to fix this though, and while nothing is set in stone yet, here's some insight into the direction we're thinking of taking it:

    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. Unmoderated comments would result in spam, misinformation, misguided or inappropriate comments, random unrelated discussions, etc. It would be hard for anyone to determine what was the good information and what was not. I'm not saying we’ll definitely never have a comments section, but currently I don't think it’s a workable solution at the moment.

    What we are thinking is to have a simple stepped process that users can go through to either give very basic feedback that we can aggregate statistically, or - detailed feedback (such as submitting new text, or a code sample) if they manage to navigate beyond a couple of basic questions. So, perhaps upon first loading a page, you may have some simple options at the bottom, however when you interact with it, depending on your choices, other options are revealed.

    For example, it could be possible to just answer yes/no to "Was this page helpful". This would give us aggregate statistics on good / problematic pages without any moderation and very few person-hours.

    More detailed feedback could be gathered if the user actively wants to report a problem instead of just giving a +1 / -1

    o Page has typos / grammar / language problems.
    o Code sample doesn't work.
    o Out-of-date information.
    o Missing explanations.
    o Unclear explanations.
    o Something else.

    Most of these could be gathered statistically too, which means we can easily prioritise reviewing pages which are getting high reports for these types of issues.

    And finally an actual text-based feedback field could be revealed if the user chooses 'something else', and possibly responding to some other questions about the nature of the feedback (so we can filter it into different categories), or by asking to suggest an improvement to the page - which again might have another simple 'hurdle' of asking the user about the nature of their suggestion or improvement before revealing the text field.

    Thanks for letting us know how you feel - we really appreciate all your opinions, and I personally also feel your frustration about the pages which are lacking information - (I also use Unity to make stuff so I’m a user as well as a doc writer!). I hope this information helps you to understand that we’re not just bumbling along or ignoring problems with the documentation. We’re actively increasing the size of the team and planning significant improvements to the docs.
     
    jwinn, Gekigengar, landon912 and 10 others like this.
  17. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    @duck thank you for detailed heads up.
    One last question - if me or someone else would to make an Advice platform, and have it render pages of doc (as in embed them on one side of the screen, while having the Advices tab on other), that is completely separate from unity on separate domain, would i have problems with copyright and all that stuff?
    Do you allow to embed doc pages into third party website that implements proposed advice section?

    Im not saying ill do it any time soon, but just knowing you are ok with that can open way to some great things.
     
  18. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I have this logic EXACTLY because I'm a programmer.

    In almost all cases you will receive most of your assistance from yourself, from documentation, and from the source code. Most of the time when you ask other people for help with ANYTHING above beginner level, you will not receive any helpful response. Not on stackoverflow (once you finish dealing with few nutcases that will insist that your question is duplicate), not anywhere else. That is how it always works, and how it most likely will always work. Community assistance stops working past beginner's questions.

    That's why I don't believe in user comments.
     
  19. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    no, youre wrong again, you are generalizing and you are plain objectively wrong. I see where you are coming with this view, but its your personal experience that you present as a fact. You are right it wont work, if you dont do anything to make it work, but people are constantly moving forward and if everyone was just as you sure that nothing can be changed there would be no progress. Think about it please.
     
    darkhog likes this.
  20. N1warhead

    N1warhead

    Joined:
    Mar 12, 2014
    Posts:
    3,884
    Man this thing is still going on 24 hours later?

    Why is this even still being discussed? If you feel so strongly about this then request it man.
    All you're practically doing now is getting on bad terms with community veterans who can actually really help you with stuff.
    I see you've been a member for awhile. But you haven't really been *part* of the community sense 2012.

    You still find your self looking at the docs still? The only time I look at the docs is if I need to find something I've never heard of, and there's not much I haven't heard of. Aside from that, I've noticed with Unity, 9 times out of 10 (for me at least). I am doing nothing but writing the same code, over and over again, just in different ways, but nevertheless, the same stuff.
    So many times it's hard to even force my self to forget any of it as it's so repetitive, transform this, gameObject this, Input this, raycast this.
     
  21. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    What about a feedback system where people basically submit an edited page of the manual to the Unity team? This would make it easier for people to submit working solutions to problems, which is what the thread seems to be about. It would make it easy for people to be precise about how they want the docs to be updated.
     
  22. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    //facepalm.
    You're human. You cannot judge things objectively.

    Adding a report buttons for errors would be decent idea.

    If you want to "discuss individual pages", you can start a blog, a forum or use unity answers. Speaking of your copyright concerns, you'll be allowed to link individual pages for sure. I do not remember unity eula saying anything about documentation restriction.

    I think it would be better idea to just have plain text/rich text form with formatting support so people can say what's wrong with the page in human language.

    Submitting the whole page would mean that whoever monitors documentation will have to diff the whole thing while hunting for errors and changes. That will be error prone. It would be better if "report documentation error" form had a drop-down menu roughly outlining the possible reason, "none of the above" which would add new field with custom reason, then large text entry field with rich text support (or markdown/kramdown/whatever) that would allow whoever submitted report to outline the issue in human-readable form. Basically, similar to what is right now used for bug reports.

    That way it will be possible to forward the report quickly to whoever is working on the docs for this or that section.
     
  23. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    Well @duck said they had a freeform submission form and it didn't work out, since people tended to be very vague and not know what exactly they wanted. By submitting an edited page you make it very precise what it is exactly you want to be changed, and in what way.

    There might be ways and means to make it clearer, like highlighting in a certain color the offending part of the docs, and highlighting in another color what you added - the latter being automated of course.
     
  24. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    why not make it automated like in diff clients.
    there are rational approaches like scientific method, and irrational like claiming things without evidence.
    you are very far from point of this whole proposal.
     
    darkhog likes this.
  25. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    Which is ultimately based on unprovable assumption that the universe you perceive is real. See solipsism.
    Either way.

    I'm not sure if people who had vague idea could somehow express it better if they could submit modified page.

    You're describing standard behavior of diff-like tools (KDiff clone, etc). There's probably a library for this kind of thing available somewhere, as long as submitted page can be converted into diffable format (rtf, plaintext, etc).

    While I'm not sure if people with vague idea could express it better if they could submit modified page (Isn't that what abandoned wiki was about?), I wouldn't object to that. As long as there's no social stuff anywhere close to documentation page. "Report the problem to maintainer" is the right way to go about it.
     
  26. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    Yes, this is the right approach IMO.

    The thing is, there could be an 'Was this page unhelpful?' button for people who simply didn't find what they wanted and didn't know how to solve their problem. But there could also be the edited page system for people submitting working solutions.

    I think the really important point that this thread brought up is the lack of an efficient way to post solutions to problems where the user solved it, but was not helped by the docs. I think the best way to do this is to send the solution to the Unity team, and the best way to send it would be via a correction to the page rather than a freeform text box that not only makes it hard to properly format the reply but also is prone to being used for complaint spamming.
     
  27. Teravisor

    Teravisor

    Joined:
    Dec 29, 2014
    Posts:
    654
    And here comes the problem: that's exactly what forums and answers are for. Docs page is only for first part of that sentence, not for second...
     
  28. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    358
    It's an interesting idea, specially if we could end up with a system that shows us the diffs - it would be a significant amount of work to build, but I'll make a note of it and make sure it at least gets discussed when we're working out what we can actually achieve with the resources we have.
     
    Matthew-Schell and Billy4184 like this.
  29. Deleted User

    Deleted User

    Guest

    Whilst documentation is very important, you could alleviate many issues by world examples. For e.g. 75% of what I needed to know about Unreal was from their tech demo's / templates and game examples. From AI to Shaders / Materials all the way up to UI and systems integrations..

    It was easier to reverse engineer and understand the process than try and search through Unreal's API documentation which in many cases was lacking and / or out of date. Don't get me wrong, I don't believe Unity's and / or Unreal's documentation is bad (relative to other engines I've tried) although a few lines of text won't have much of a practical use to a beginner or even intermediate level coder (within Unity's API) in an implementation sense.

    From the FPS Multiplayer demo (which is a short version of a high production release), I picked up workflow examples I never previously thought about. It also enabled me to wrap my head around what they were trying to achieve..

    So I'd personally like to see common game scenario's which you could reference API use in your documentation (to give them some real world application), say for more information see this demo: < Insert link >.

    Yeah, I understand there are frameworks and many tutorials (third party).. Although quality varies vastly, even some of the prototype (standard assets) would never be useable in an actual game. I'm not sure I understand their purpose?

    I can't remember thinking, wow Epic you really don't know what you're doing. Most examples I've tried have been excellent.

    It might be good for Unity as well as your users.
     
    Last edited by a moderator: Apr 4, 2016
    Billy4184 likes this.
  30. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    You're missing the fact that for the docs team to be effective they need to be alerted when there's a problem, it's all well and good to have a forum but you can't expect them to go looking for problems there. There needs to be a way for people who have found good solutions to problems to be able to effectively send it through to the team. For more vague problems, the 'Page Unhelpful' button would probably go a long way toward flagging places where a lot of people did not find relevant information.
     
    darkhog likes this.
  31. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I believe that in case of "unhelpful page" it would be necessary to know what people were looking for, but in that case you're very likely to end up with vague or unhelpful information.

    Speaking of which, it would really help to have transcription for all the video tutorials. I really hated those. It is impossible to Ctrl+F through video for a spoken word.
     
    Teravisor and Deleted User like this.
  32. darkhog

    darkhog

    Joined:
    Dec 4, 2012
    Posts:
    2,218
    Actually this system could work just fine, with one tweak: each of
    would provide an optional (ie. you can leave it empty) text field to provide details of what is missing, which is especially important for long pages.

    E.g., let's say somebody put mark in "Unclear explanations" section. That's nice, you got that datapoint of statistics. But the page in question is particularly long and deals with many things related to its topic. So what EXACTLY is unclear? Having additional "details" field would let people fill in what is unclear to them and perhaps a suggestion of improvement if somehow that person managed to understand but had hard time doing so and know of a better way to word that info so other people will understand it better (and perhaps that person's future self if he or she forget solution to the problem and will have to deal with it again).
     
  33. darkhog

    darkhog

    Joined:
    Dec 4, 2012
    Posts:
    2,218
    So you now using a webcomic as an argument? FYI "comic" part is important. It's meant to be funny and not taken seriously. That part was objective. And this comic hasn't been decently written since 6 years ago. That part was subjective.
     
  34. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    It would be better to have more detailed information but it was made clear that a freeform text submission did not work since it was too difficult to sort out the real problems. A page that had a lot of flags for being unhelpful could be given a check by whoever worked in that department once it received a lot of flags. Someone is designing these manuals after all and it would probably not be too difficult for them to figure out why it was getting those flags.

    The main problem seems to be resources, and the flag 'Unhelpful' system seems to be a good way of making a simple first pass for bigger issues with the docs. Beyond that it gets more difficult.

    However as I said before, the main thing for me is an easy way for knowledgeable people to post fixes to the manual to the Unity team so they can make updates. This is @pointcache's main point I think, because as he rightly points out when you've got information that can help other people out, how do you get it to them in an efficient way? Right now there's no real way of doing this at all. You can post it on Answers but the only people who can put it in front of everyone's eyes in an easily accessible way are the Unity docs team, so you have to get it to them. The bug reporting system is too inefficient for this.
     
  35. darkhog

    darkhog

    Joined:
    Dec 4, 2012
    Posts:
    2,218
    MediaWiki software does exactly that.
     
  36. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,009
    I totally support this. For problems beyond syntax and simple code snippets, it's much easier IME to reverse engineer a well-done system, and I wish that Unity had more sophisticated playable examples from common genres, rather than prototypes which don't so much reflect a game as much as they reflect a demo of some particular feature.
     
    Deleted User likes this.
  37. steego

    steego

    Joined:
    Jul 15, 2010
    Posts:
    969
    The problem with playing the numbers game is that the worst documented parts of Unity are also the most obscure and least used, so these pages wouldn't get as many votes anyway.

    Also when one's dealing with the obscure parts, that's when the documentation is the most valuable, because it's impossible to find the information elsewhere. It's been quite a few times I've come across stubs in the documentation, and when I try to google it, all I can find is an unanswered post on answers by denvercoder9 from 2003.


     
    jwinn, Gekigengar, landon912 and 4 others like this.
  38. Teravisor

    Teravisor

    Joined:
    Dec 29, 2014
    Posts:
    654
    Maybe filter those "bug reports" to article using community filter?
    If page really requires rework, you upvote it, UT team reacts sooner.
    If that "bug report" is bad, you click downvote it, UT team reacts later (or never, too many downvotes and "bug report" is removed even before UT team sees it).
    If page is obscure and least used like in @steego scenario it will remain at 0 votes leaving it in non-priority queue that will be checked when hands come to it. Maybe increase its priority with time if it's ignored by community for long? Or maybe someone will stumble at it after 5 years and upvote it (though system should try to prevent such long wait), and it will actually be answered someday sooner.

    Reason for this idea: reduce workload of UT team caused by bad "bug reports"(or whatever else you'll call it, thus quote marks). Causing increase in amount of articles processed and enhanced.

    I'm sure @neginfinity will rage on my proposition now. It's essentially same as comments because it will be linked directly with the page (looks like either button or comment section).
    Or someone else will rage on me saying that's same as feature requests. I just feel it. (It's not if you think a bit deeper).
     
    Last edited: Apr 4, 2016
  39. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I would suggest to apply both logic and sense of humor to this.
     
  40. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    358
    There is a documentation section on this forum, and we do watch it and respond, but it's not a great use of our time and it's a particularly inefficient method (for you & us) of getting simple small issues fixed. We'd like to make the docs feedback much more efficient for the vast majority of simple cases. My guess is that most errors go unreported because users don't want to go through the effort of making a thread/filing a bug report etc.

    We also have the page hit statistics, so we can look at the downvotes as a proportion of total page hits to correct for that problem.

    We'll be doing lots of tweaks and refinements to the plans before we put it out, what I posted was just a general outline of the idea :)


    Thanks all for your feedback. I think it's time to lock this thread, since amongst the nuggets of useful info and suggestions there has - for some reason - been a lot of heated emotion and ad hominem attacks. Glad so many of you feel that passionately about the docs! I think most of the sensible ideas have been covered, and if you feel like you have any genuinely useful or interesting new conversations to start based on this, please start a new thread.
     
    jwinn, N1warhead and Yukichu like this.
Thread Status:
Not open for further replies.