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. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    yeah me too man. thats why this op post doesnt mention wiki anywhere.
     
  2. landon912

    landon912

    Joined:
    Nov 8, 2011
    Posts:
    1,579
    *rolls eyes*
    Come on now. Let's try to play nicely.
     
  3. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Im just doing what i have to, im promoting comment section it is unrelated to wiki. I dont know what you mean.
     
  4. JamesLeeNZ

    JamesLeeNZ

    Joined:
    Nov 15, 2011
    Posts:
    5,616
    I've seen plenty of vague documentation. Its never stopped me doing what I need to... If you cant figure it out, youre probably not much of a developer.
     
    Yukichu and N1warhead like this.
  5. N1warhead

    N1warhead

    Joined:
    Mar 12, 2014
    Posts:
    3,884
    Desp
    That's mainly why I haven't responded, because there's ways of finding the answer. In fact I think searching for answers can make you a better developer because it means you're actually trying to learn, not a quick fix to get your code high lol.
     
  6. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    I don't enjoy wasting time, i don't need to prove anyone im "much of a developer".
     
    Teravisor likes this.
  7. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    And despite there being real benefit to proposed system, you are still against it. What your position achieves?
     
    darkhog likes this.
  8. N1warhead

    N1warhead

    Joined:
    Mar 12, 2014
    Posts:
    3,884
    Why can't anyone just accept the fact that they are doing their thing for the reasons they want to do it that way. If anything your point has been heard by Unity Tech people, chances are they'll mention it to colleagues, if it gets done it gets done. There's nothing else really to say about this. Perhaps if you have been nicer your point would have been more clear. One thing that will get you pushed to the side by the Unity people is someone who bluntly arrogant pushing the point across.

    What's wrong with a nice message? I mean is a nice message so hard to be heard?
     
  9. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Im not sure what to respond. Starting with the fact is asked excuse for being rude, but well. You are assuming people at unity mix emotions with the business? So because of the fact i was rude now everyone else who supports this proposal should suffer? I don't think im the one arrogant, i just think that if idea is good it should be done, and it benefits me a lot, thus i will push it until its ether done or declined, i see nothing wrong with it, its how things are done in real world.
    Nobody will change anything until the voices are raised. You are satisfied with current state of things? Im not.
    And the hell with it, i don't care if i sound arrogant or not nice, i want things done, or any indication that something will change to better, sorry if i dissapoint you in any way, not intentional, thats how i do things.
     
  10. JamesLeeNZ

    JamesLeeNZ

    Joined:
    Nov 15, 2011
    Posts:
    5,616
    You don't enjoy wasting time, but you're in game development? Sounds like an oxymoron to me ;)

    Just learn to live with it tbh... Unity have bigger fish to fry without tripling the documentation work load...
     
  11. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    No. Ok i think im just too carried away with protecting this. I respond to your opinions as to attacks, and thats a sign i need to stop. Please if you support the idea, don't hesitate to show it, if you are interested read first page, over the course of discussion we narrow down how the comment section can benefit everyone with little effort from Unity team.
     
    Last edited: Apr 4, 2016
  12. N1warhead

    N1warhead

    Joined:
    Mar 12, 2014
    Posts:
    3,884
    @pointcache - I understand what you mean, but you got to realize - the world doesn't revolve around 'you'.
    And you're right things don't 'always' happen until voices are raised, but then again, sometimes people get them and their families executed for doing so, no I am not saying Unity will execute you and your family, the point I am trying to make, just because you raise your voice and start cussing it has nothing to do with mixing emotions and business, only that you are being self-centered and speaking for only 'you'. As you keep saying "I", "me", "I'm not", which is nothing to do with you speaking for the community as a hole, but of your self.

    Fellow community members chipped in and voiced their opinions of how they would like the idea, but for some reason you keep sticking to being self-centered about it, it's all about you and you only. You could open the box and start thinking outside the box and maybe get things done.

    You don't disappoint me, in fact I could careless if you offend me as it doesn't bother me, everyone is entitled to their own opinions, you believe what you want and that's absolutely fine, but realize the world doesn't revolve around you.

    You could go do a feature request on that one page and maybe it will be put in with enough votes on it, so instead of voicing your frustration turn it into action and maybe it might get done.
     
    Acissathar likes this.
  13. JamesLeeNZ

    JamesLeeNZ

    Joined:
    Nov 15, 2011
    Posts:
    5,616
    I think so... its obvious youre passionate about this subject.

    I would like better documentation. We're on the same page there.

    I dont want it to be user controlled though. Way too easy to end up a bunch of mis-information. Too many stupids ruin pretty much everything for everyone at some point. This will likely go the same way.

    It might work, it probably wont.
     
    zombiegorilla likes this.
  14. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    I deliberately said "benefit me" and alike because as a user and consumer i represent people who work with unity engine, and this proposed system will benefit me, you and anyone else.
     
  15. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    The comment section and pages are separate, pages are controlled completely by unity without users being able to affect them, comments complement and add tips and tricks and other things that you may or may not find useful, but with time every potential issue you can come up with would be discussed in comments and solutions to most common problems will float on top with higher ratings, look at stack overflow for example.
     
  16. N1warhead

    N1warhead

    Joined:
    Mar 12, 2014
    Posts:
    3,884
    Then I just can recommend putting it in the feature request thing, I know it's here somewhere, I've never had to use it though. But that's where you can put your idea to action. Just make sure it's very well typed out (neatly).
     
  17. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Thats a great advice and i will or someone else, i just want to make sure that there is enough supporters so it doesnt die, and all efforts and discussion here would be in vain.
     
    N1warhead likes this.
  18. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I'm strongly against it and I think it is a horrible idea.

    MSDN has it, and it is completely useless. MSDN also became worse after the system was introduced.
    One of the examples you listed, Stackoverflow, is THE worst programming community on the internet. Due to adherence to karma and rules, the site went to hell (from being a useful resource) in a few years and is right now completely useless.

    I do not want to see questions on documentation pages, and I do not want see some folks feeling proud and entitled becauser their karma counter is bigger.

    I want documentation without nonsense or irrelevant info. So I do not want documentation pages to be turned into another "social" site.

    Right now documentation is okay. Any sort of comment section will only add noise and make it worse.
     
    ramand, landon912 and N1warhead like this.
  19. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Define useless
    Highly opinion based statement.
    By design the karma must be per post to avoid this issue. So no global counters.
    Nobody forces you to use, or even open comment section.
    The documentation wont change, the comment section is added as a separate tab/panel and is optional.
     
  20. landon912

    landon912

    Joined:
    Nov 8, 2011
    Posts:
    1,579
    Am I the only one here that thinks that the Unity documentation is pretty damn good for a giantanormous(I feel the need to invent a word to describe the degree of size) code base? I've seen few better at this size. I've seen plenty worse. Just keep improving Doc team. :)
     
  21. JohnnyA

    JohnnyA

    Joined:
    Apr 9, 2010
    Posts:
    5,041
    Is everyone bashing @pointcache because he dared to disagree with a Unity employee (one who like a few others seemed to completely miss the point that @pointcache clearly said he wanted publicly editable comments not publicly controlled documentation).

    PS I don't mean for example @neginfinity, its completely reasonable to have a differing of opinion (he doesn't like public comment sections).
     
  22. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    The proposed system is optional, sits in its own tab and does not affect actual documentation. For exactly this reason, no everyone likes the idea, but it doesnt mean that the idea should not exist. Both parties will be satisfied as nobody enforces the usage of comment section and the comment section does not magically spill to mess up already existing documentation. However once you stumble upon yet another issue with something not working as described you will just have to switch to comment tab and chances are the first comment with contain clear explanation on your issue, because typically everyone experiences the same issues.
     
  23. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    Does not provide any information related to the problem I'm trying to solve.

    I wasted few years on that PoS site, and had about 17k rep here. I also remember how it went to hell.
    Good luck trying to change my opinion about it.

    By design, there should be no karma, and no public comments allowed.

    In any Karma-based system user will form a core group which will then act as a united whole against any "outsiders". The said group will act hostile toward anybody who disagrees with it.

    Karma counter only indicates how many people agree/disagree with a post, but that does not mean that people who are upvoting/downvoting aren't incompetent. So in the end, you'll only be adding useless noise.
    It is not a good metric for post validity.

    In addition to that, in text communication people act with increased hostility (due to lack of empathy/non-verbal signals, etc), so instead of helpful community, you'll need a new moderator team for brand new kindergarten you created.

    No. Absolutely no comments or any "social" aspects on documentation anywhere. I want documentation, not dealing with b*******. No comments, no likes, no dislikes, no karma, and no social nonsense. Just documentation. Let the documentation team handle that instead.

    There are absolutely no benefits from your proposal.
     
    Yukichu likes this.
  24. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    at the start of the thread the first two posts werent centered about comments until
    at this point the focus shifted completely to comments but Andy still took a long time to realize it and i got salty, for which im sorry. i would rather forget this dumb drama caused by my saltiness and just focus discussion to the topic.
     
  25. seitor

    seitor

    Joined:
    Feb 18, 2012
    Posts:
    36
    Good idea. Here is an example, in Unity 4.X, you want to move rigidbody(iskinematic true) with MovePosition not transform.position because it would be cheaper to use MovePosition.

    It would save me several google search and digging through forum post to get this tip. So yay I am all for a comment section.
     
  26. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    I think you misread, the tab with comments is optional and nobody forces you to open it. Im sad you had issues with SO, it was very helpful to me, high rated comments as well as low rated comments. In system that doesnt allow you to accumulate "points" but only applies them to post, there is no way to create "groups" as only each separate post content is judged.
     
  27. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    Yep. I deeply regret the loss of the original stackoverflow from 2005. That was a useful community with helpful people. It was destroyed by karma system (the site pretty much got team of lunatics running it in the end, so right now the only way to fix it is to kill it with fire).

    Unity documentation is decent. It is not Qt 5 level documentaiton, but you can always compare it to Unreal 4 documentation for C++. A "report a problem" button could be useful, but any kind of social feature on this page will only hurt the documentation instead of improving it.

    The bottom line is that I do not want people trying to interact with each other anywhere close to documentation page I'm reading - nothing good will come from it. If someone needs suggestions/help, they can always use forums/unity answers, and for sandbox pages there's a wiki somewhere.

    Just Don't. Touch. Documentation.
     
  28. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    So a separate tab that is not affecting the actual documentation and you are not in any way forced to open, where other people who would enjoy that will be ok for you?
    Technically the only difference for you would be another button on the top "Comments" but the rest of the page would be the same.
     
  29. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    Yes, I'm still against it. It does affect actual documentation by existing on the page, and potentially providing a distraction.

    I'm still against it. No social aspects on documentation. Not on second or whatever tab.
    "Report a problem" is okay, making pages on wiki is okay, using answers/forums is okay.

    Mirror the documentation elsewhere if you have to and have fun there.

    There is. A prolific user with high post count can accumulate a following which will then defend their "leader". Same thing.
     
  30. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Again the ratings are per post and not accumulated anywhere. There are no counters/post counters/carma counters.
     
  31. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    Clarification: I'm against any kind of "social" online interaction by community users that can be reached from documentation page, because it will only generate noise and nothing more. I only want official information that came from dev team, and not what was written by someone else.

    There are already ways to help each other and post solutions that can be then found with google.

    Unity Answers, Forums, and wiki. Heck, you can make a blog if you want.
     
  32. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Sorry but you are irrational, if you are not switching to comments tab it does not affect you.

    You are saying that if you dont like bread nobody should be eating bread near you and only in certain places where it satisfies you.
     
  33. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    It does. It exists on the page, i see it, I can click it and therefore it affects me.

    It is also one of the rational opinions I have.
    I value information. A social aspect on the documentation page will not contribute to information, but instead provide a place for people to squabble. Therefore it is not needed.

    Now, I think it would be helpful if you explained do not want to use the wiki, Unity Answers or the forums for those purposes.

    -----EDIT-----

    Either way I think you might be assuming that a comment section on documentation will attract a large number of highly skilled users (each with 50 years of experience using unity engine) who will be looking for problems.

    In reality, instead you'll have a horde of users which will be mostly not skilled. So, those people will mostly generate noise while not contributing to documentation quality.

    The main problem is that people that know ANY product well are not that common, are hard to come by or are usually already employed anywhere. The good news is that some of the more skilled guys are employed at unity and may be even working as a part of documentation team.
     
    Last edited: Apr 4, 2016
  34. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    You are contradicting yourself as comments and all the useful stuff that can be there are valuable information for everyone it depends on are you able to use it or not.
    There are thousands of questions with zero answers on all of those, there are gazillion unresolved issues and threads/questions on missing/broken/misleading documantation pages that are one liners and dont reflect real states on things in unity engine. Using comment section will deliver useful information to people who need fast explanation on per page issues that arise because of documentation faultiness, as well as adding new useful information beyond that that can help a lot of people.

    This thread is about a useful tool that can help me, and other people giving instant help on most common issues.
    You are judging the tool that is objectively superior to other tools by your criteria that comes from you negative experience. Again you contradict yourself stating that in 2005 SO was good, and now in your opinion its bad, yet SO was back then a social platform and not documentation.
    Please if you have any objective arguments against my proposal, apart from undefined "noise" i will defend my position, but your issues fall out of rational and objective category and i personally wont respond to them.
     
  35. Player7

    Player7

    Joined:
    Oct 21, 2015
    Posts:
    1,533
  36. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I'm not.

    It won't, because you'll have same number of the same people with the same skill, except that now they'll have access to comments on the documentation in addition to forums/answers.

    WHO is going to write "useful and helpful comments"? There's no army of programmers waiting to jump at the opportunity. The amount of attention you get on unity forums/answers is what you get from pretty much the whole globe.

    As I said in previous post, you appear to think that there is an army of highly skilled people waiting for comment section to appear so they can start sharing their insights with you. To my knowledge that's not the case. Instead you'll have clueless newbies wandering into comments. Those guys will generate noise. And that's why I'm against this feature.
     
  37. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    I was around, just never had interest in php, and keep in mind that php had significantly bigger audience than unity.

    Yup. I quit when community went insane after I rolled back an edit on my own post I wrote 3 years ago. Apparently that action made me a spawn of satan or something.

    Either way, I'm going to sleep for today.

    I outlined my point/arguments, no reason to argue further. Have fun, guys/girls.
     
  38. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    You appear to think only newbies use documentation, yet you are very picky with how you want to see your documentation. Again opinion based, no facts provided and you are neglecting that it will in fact help people reach their goals faster than other means, thus saving time and money.
    ill start.
     
  39. JamesLeeNZ

    JamesLeeNZ

    Joined:
    Nov 15, 2011
    Posts:
    5,616
    Even as a feature request, it would require a large number of support votes. Most of the people responding in the thread don't support the idea, so I would just let it go, as nothing said in this thread will change any minds.
     
  40. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    No.
     
  41. JamesLeeNZ

    JamesLeeNZ

    Joined:
    Nov 15, 2011
    Posts:
    5,616
    Good to know you're just hear to argue...
     
  42. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Im arguing in favor of the useful tool that can save me and other a lot of time, what are you arguing for is a mystery to me.
     
  43. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,010
    I can't really comment on how well your idea would work out @pointcache but I have to ask why you think things are so bad with the documentation? Unity has far and away the best documentation, tutorials and learning materials of any piece of software I've ever encountered, not to mention being a particularly user-friendly software to begin with. My biggest problem with it has always been lack of features and capability, compared to other engines, but to Caesar what belongs to Caesar, it's really a model of how software should be presented and supported.

    Perhaps your idea would work out, perhaps not, but any new thing will take a lot of time, effort and money and so far you haven't presented, IMO, clear evidence of how useful it would be compared to just having Unity forums, answers and so on. And in view of that I'm inclined to agree with @neginfinity that it would probably be more of a distraction to me than a help.

    So what's stopping you from stepping over to the Unity forums or answers when you have a problem to solve, or is it somehow necessary to have it on the same page?

    If I remember correctly you had a recent thread about how unhelpful the forums and answers sections were, so I don't see how the system you're proposing would be any better, since it basically works on the same principles?
     
  44. pointcache

    pointcache

    Joined:
    Sep 22, 2012
    Posts:
    577
    Because its not based of someone asking.
    It is a direct "tip", find second post of mine in this thread with examples of bad documentation(and thats just a small fraction of what i encountered over the years with unity) , now after i struggled with some really unobvious issue due to lack of documentation, i would add a short "tip" to the comments section describing what and how exactly i solved it and so on. This is not "ask and wait for nobody to ever answer because its too specific" it's - "oh let me check, oh look this guy already had this same thing and he shared it without the need for me to ask about it."

    Again 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.
     
  45. JohnnyA

    JohnnyA

    Joined:
    Apr 9, 2010
    Posts:
    5,041
    I think the 'nays' points are something along the lines of:
    1. Adding a new features takes time.
    2. Moderating this new feature takes an ongoing time commitment.
    3. You can already easily find similar community driven information via google, answers, etc.
    4. It breaks the separation between clean, formal, approved documentation and social unmoderated 'help'.
    5. The actual value of the feature is not as high as you think it would be. Due to:
      • A lot of noise
      • Not that many experienced users will go and update the doco as a matter of course
      • Even useful comments may be become noise as they become out of date

    The conclusion: Given 1, 2, 3, 4, & 5 this time would be better spent on another approach such as hiring more Unity experts to address documentation issues, and teaching users to utilise the "Report a bug" feature of the documentation.
    You may not agree, but its hard to say there's no reason at all behind the viewpoint.

    Personally I'm on the fence: I've seen this approach work, but I've also seen it fail miserably.
     
    Yukichu and neginfinity like this.
  46. Billy4184

    Billy4184

    Joined:
    Jul 7, 2014
    Posts:
    6,010
    Well I think there's an issue to be addressed here. For example when I've figured out something that I didn't get a clear explanation on from the docs, in the past I've necroed old questions with my solutions in an effort to help people who are searching for answers. I think the 'tip' method is something that should be implemented somewhere.

    However I'm not totally sure that it shouldn't be implemented in the forums/answers, since that's pretty much what those sections are for. I would support the ability to post solutions on the answers section without having to ask a question. I don't think it requires creating a whole new section. And I have to say I'd rather keep the docs section for Unity themselves.
     
  47. iivo_k

    iivo_k

    Joined:
    Jan 28, 2013
    Posts:
    314
    Personally I would never waste time reporting a bug regarding documentation and wouldn't create a forum thread about it outside the beta forums either. I could write a comment to the documentation page though.
     
  48. Ostwind

    Ostwind

    Joined:
    Mar 22, 2011
    Posts:
    2,804
    Seems that some people here have not read all the suggestion posts, are here to troll or think the community is full of dickheads waiting to spam community section of documentation?

    It's already been said that the new section would be for additional notes, tips and examples and not for questions. Documentation itself would not be touched and could have this other section as collapsed by default. Also it was said that the access could be easily limited to certain groups and last resort, the voting system.

    Similar systems are out there in various places and have worked out well.
     
  49. neginfinity

    neginfinity

    Joined:
    Jan 27, 2013
    Posts:
    13,554
    No, I think that only non-newbies can contribute to the documentation (in useful fashion), and there aren't enough of those.
    With both Unity/UE communities with complex issues you're on your own.

    Your proposition itself is opinion based. "Comment section will improve documentation". That's an opinion/belief, not supported by facts. Calling reddit/Stackoverflow "successful" is an opinion. "Does not require attention from unity team" is an opinion (it will require attention - to moderate it).

    And you already have ability to share tips/tricks using other means, which you stubbornly ignore. Assuming that comments will be better than those is also an opinion.

    Yes, that's pretty much it. Good job summarizing it.
     
  50. r618

    r618

    Joined:
    Jan 19, 2009
    Posts:
    1,303
    @pointcache I'd remove social examples from the OP;
    I agree with @neginfinity that SO became heavily 'gamified to the point it affected the real content and reddit is not a shiny example of technical content either
    social examples imply bad conotations and move the discussion in wrong direction
     
Thread Status:
Not open for further replies.