Search Unity

  1. We would like to hear your feedback about Unity and our products. Click here for more information.
    Dismiss Notice

documentation of new API still vastly underdeveloped

Discussion in '5.5 Beta' started by laurentlavigne, Nov 24, 2016.

  1. laurentlavigne

    laurentlavigne

    Joined:
    Aug 16, 2012
    Posts:
    2,012
  2. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    356
    Hi - it seems to be a common misconception that "fixing the docs" is a fairly easy task that no-one is bothering to do, and could be done relatively quickly if we just got on with it. Unfortunately this isn't the case, and I'll try to explain why.

    The docs team are seven people, with five of us having joined the company this year.

    There are approximately 1200 user manual pages, and 13,000 API reference pages.

    Of these 13,000 API reference pages, about half have fewer than 100 characters of documentation. These are already on our list as pages requiring attention.

    However the task of bringing all existing pages "up to scratch" is monumental in scale for a team our size. What I mean by "up to scratch" is that each page should have more than 100 characters of written explanation and at least one example script.

    Communicating with the developers and double checking the exact meaning and usage of each API member when writing the docs is a time-consuming process on both sides (for both us and the developers - they are of course working on other things too), and so - realistically - if a docs team member were to focus on this task all day, I would estimate that they could fix between 2-4 pages per day. Some single pages can end up taking more than a day, but I'm going with 4 as an optimistic estimate.

    However, going on this (highly optimistic) estimate of our whole team of seven, working all day, every day on this task, and fixing 4 pages per day (of the 6500 sub-100 character pages), it would take us 232 working days.

    Given that there are only 261 working days per year, and we kind of have to let people have holidays, this is pretty much an entire year of 7 people working flat-out, using the most optimistic estimate of how fast we could get work done.

    However - we can’t put all 7 people on this task because we have lots of other considerations. For example, it doesn't take into account:
    • Having other team members proofreading the content (which is a vital part of our standard writing process).

    • The work involved in publishing the docs online, and ensuring it gets included in the installers for each version of Unity

    • Grafting improvements and fixes between versions of the manual (for example, if we make a fix in our “main” branch (currently based on 5.6) we have to make sure those changes are carried across correctly into the 5.5 manual and the 5.4 manual. Sometimes these pages differ between versions so grafting changes isn’t always straightforward.

    • And - of course - documenting all the new features coming to new versions of Unity during that entire year! (with 300 developers constantly making Unity do new stuff, that is a lot of work!)
    In fact, documenting new features forms the vast majority of our work and takes priority, which is why attention to improving legacy documentation has to come in at a lower priority.

    We do understand that under-documented pages like the one you highlighted are annoying, and we hope to be able to improve the situation, however the sheer scale of the problem is largely "hidden" because it's difficult for an end-user to get a picture of just how many pages there are. We are hoping to further expand our team in the new year, and it may be that we can eventually have some people assigned to this full-time, however in the meantime we're doing the best with what we currently have!
     
  3. Player7

    Player7

    Joined:
    Oct 21, 2015
    Posts:
    1,350
    Can you put the script stuff at the bottom of these doc pages.. where it should be if you must have it added to offline docs! It is common practice to put such script content at the bottom of the page source, especially for these type of web pages, so that browser displays the page before doing what js wants to do.

    As it hangs poor browsers like IE and I have it firewall blocked which doesn't help with it being unable to contact the borg, and as Unity doesn't let me specify help pages should be opened up in a better browser its really annoying. Because these help pages take ages to draw simply because of this crap hanging the process.

    Its literately faster for me to search a unity help issue online and have it display in firefox, than it is for me to open the local unity docs offline in IE and search that...and yet it should be the quickest way ideally.

    And I took a look into it and it is this one broken ass line of google crap... <noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-MC35ML" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>

    that causes a blocked IE to take over 20seconds to load up a offline doc page....(I think even unblocked it was hanging way to long to display the page)

    notice the missing http:

    <noscript><iframe src="http://www.googletagmanager.com/ns.html?id=GTM-MC35ML" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>

    with it fixed it loads up practically instantly.. now if you could just fix that in the 10000's doc files that would be an improvement. And even faster when you put the rest of the scripts at the bottom page source, the Unity help sidemenu being loaded after the main doc page is displayed makes more sense to me.


    As for the actual doc content.. yeh yknow after that forum topic that got locked months ago what is really missing... is a user feedback page and a history page to show what was last added/changed in a timeline, I still think the php documentation with feedback works really shows how it can work well and there docs are much better... and for these beta's it seems nothing really changes per beta install with the docs.. The 'What's new' section for each unity version has some stuff.. really hard to see what gets added overall though, scripting api side of the docs no way to see whats new, changed depreciated etc.

    And frankly with 300 devs, they should be documenting and providing more code example usage for the api and features they add into the engine anyway. Even if its some scrap example code from test projects showing those particular api's being used to get glimpse of context usage etc.. anything better than nothing, especially for newbies. I wouldn't expect doc team of 7 ppl to come up with good example code for each api function but right now its hard to see much of anything being improved in the docs for us to track.. yet tons of analytic tracking in the doc pages, is it really that helpful? :cool:
     
    laurentlavigne likes this.
  4. greg-harding

    greg-harding

    Joined:
    Apr 11, 2013
    Posts:
    371
    laurentlavigne likes this.
  5. Peter77

    Peter77

    Joined:
    Jun 12, 2013
    Posts:
    3,601
    Have you thought about "Is this page helpful [yes/no]" buttons on each documentation page? Microsoft has this on their MSDN pages, eg here (at the bottom).

    It could be used as an indicator to understand which pages (most) users have problems with and prioritize these pages, rather than going over all pages. I think there are quite a few pages with less than 100 characters that do a good job, such as this one for example.

    Submitting and evaluating Is this page helpful is probably less work/overhead, on both sides, than going through the Unity bug-report process.
     
    laurentlavigne likes this.
  6. laurentlavigne

    laurentlavigne

    Joined:
    Aug 16, 2012
    Posts:
    2,012
    There are many ways to tackle scale:
    1. Implement @Peter77/Microsoft feedback but only with stars and a red flag because text would cause another bottleneck, unless you have a google intern who could write you a semantic parser.
    2. Involve the community! Like the code, open source it. Have a version on wikia where everyone can pitch in. When a page gets 1 starred too many times, automatically flag the corresponding wikia entry for review by a moderator, once it passes the decency filter copy it over the offical doc and flagged that page down you team's queue.
    3. Award the community. Asset store credit >> tshirts ;)
    4. Simplify! For example lose the new JS front end. It's slow, incompatible, very buggy, can't parse command+' properly, forgets opened sections etc...
    5. Formalize how information is presented. That's a super hard problem, in university we had one course on it, a 70 year old professor was teaching that a bit of a genius, it was so abstract and encompasses so many disciplines that it actually sounded arcane, like making potions. Try this formula:
      1. complete dependency in link: UnityEngine.EventSystems.IPointerClickHandler
      2. super concise description: "OnPointerClick gets called when a pointer (mouse, touch, future device) clicks on the attached collider".
      3. usage case: "If you want to detect click on an object and have the event not go through the GUI"
      4. warnings:
        • "OnPointerClick on a scene object requires a PhysicsRaycaster on the main camera" (this should raise an error in the console)
        • "OnPointerClick requires the interface IPointerClickHandler" (if IPointerClickHandler isn't implemented but OnPointerClick is in the code, a warning should be raised in the console)
      5. code sample or link to code sample page
      6. image
      7. stars and flag & link to wikia on the same line
     
    Last edited: Nov 26, 2016
    StaffanEk likes this.
  7. Player7

    Player7

    Joined:
    Oct 21, 2015
    Posts:
    1,350
    really jeeez.. I wish I had known about that fix earlier, I only bothered taking a look into it source code of it yesterday, such an easy fix when you find out about it... to see that the problem code was already identified earlier, even though I know for a fact it has been a problem for way longer than that... docs team o_O
     
    laurentlavigne likes this.
  8. Alex_May

    Alex_May

    Joined:
    Dec 29, 2013
    Posts:
    147
    Recently during a hack week the docs team developed a prototype feedback system that works like you suggest. We are waiting for a good time to implement it as our resources are stretched thin at the moment and we currently cannot take on the extra work of processing this data. There's a video of it floating around somewhere.

    Part of the reason the docs are in the state they are in is because historically we had no controls on what was entered into it by the development teams. Opening up the docs as a wiki with moderation and filters presents the following problems:
    • Lack of editorial control. Suddenly you need several staff members to go through all the additions, which are already public and possibly quite poorly written by people who have english as a second or other language. Why not just pay some actual technical writers to write the docs, at this point?
    • Lack of content control. Content could be outright wrong for whatever reason. Now you need members of staff to check and test the additions to make sure it's all true and correct, instead of how we have it now, where the information comes from the development team and has been through many tests and reviews before hitting the release trunk.
    • Ethical considerations of unpaid work, only muddied by grey area reward systems like asset store credit.
      • To whom do you allocate credit, and who on the docs team is being paid to spend the time doing that instead of actually writing docs?
    • If you open up one professional area of Unity to the public, what does that say about its value? Why not open up the web code to the public? The code for our ad network service? The engine code (which as far as I know is not open-sourced at the present time)? Maybe the public could just write the engine? I know your intentions are good but what you are saying devalues us as a professional team, just like the suggestion that we could get it all done in a month if we just asked the developers some questions about each page. Do you not think we already do this?

    Thanks - we would love to simplify the docs front end. It would give us a lot, like being able to switch from the manual to the scripting API or between Unity versions without being kicked back to the front page of the manual/API. There's a lot of old code in there we would like to ditch. We're actively looking at professional solutions.

    Great ideas. I would personally like to formalise and standardise the namespacing. I haven't looked at our back end code enough to know how easy or hard that is, but I know it's confusing both for users and for us as a team. Right now (and we don't plan to change this at the moment) we have a summary line and then a detailed description that can include prose, examples, and images along with notes and links to other relevant pages. The order of this information is not currently formalised. I think a formal order of presentation of this information is a great idea. I'll mention it to the team.

    Thanks very much for your input! I hope my reply has been useful in helping clear up some of the perspective on this.
     
    laurentlavigne likes this.
  9. laurentlavigne

    laurentlavigne

    Joined:
    Aug 16, 2012
    Posts:
    2,012
    There is misunderstanding of the goal of open sourcing the doc: not a replacement, merely helps undersized teams plug holes. Where do you think Gary's mod come from?
    More details below.

    You're a small team as you said. Let the community do this job: star rating wikia will take care. You then get intersection 5 star wikias and 1 star official doc and auto fill.

    Star rating + some of us who can write english good + you'll see moderator float up because loads of us are frustrated book writer (btw you mention being paid as a quality factor ... are the forum moderators paid?). Some of the doc isn't the best english and proper syntax doesn't matter much to me as long as it's concise and clear... better than nothing.

    Get one very good web coder he/she'll automate all that.

    It doesn't say anything about its value, it just reiterates what we all knows since Gaben: that 10, 40, 80 people are far less productive than hordes of thousands.

    Because you'd have to open your servers which would make you sensitive to hack.

    Because it would give access to algorithm which would make ad more sensitive to hack, also give access to rates which are under NDA.

    Doubtful because the public is good at making bits ok-good, not a whole coherent. Also open sourcing would open the engine to being replicated by competition.

    That's a debate I won't get into, just talk to the dev team see if their open sourcing so much of the engine makes them feel devalued.
    Here is a good process I used many times when facing discouraging amount of work: seed then iterate. In this case start with one line then later on you make it nicer. This gives us what we need and you eventually get what you want, to express things nicely.
     
    StaffanEk likes this.
  10. Shizola

    Shizola

    Joined:
    Jun 29, 2014
    Posts:
    174
    I appreciate this is not an easy job... but some of these problems should not be happening.

    For example in March I reported that several of the documentation buttons in the editor point to dead links.

    https://fogbugz.unity3d.com/default.asp?767388_0n98f2stqc7ih36c

    6 Months later I got a reply saying, it was fixed it, (It wasn't). Not a good experience if it's your first time using Unity. Something the community could have fixed in 2 seconds.
     
    Last edited: Nov 28, 2016
    laurentlavigne and StaffanEk like this.
  11. Player7

    Player7

    Joined:
    Oct 21, 2015
    Posts:
    1,350
    yeah and I just want to know that the below issue will be fixed for future offline doc installs.

     
    laurentlavigne likes this.
  12. greg-harding

    greg-harding

    Joined:
    Apr 11, 2013
    Posts:
    371
    It's great to hear that documentation is getting more attention. Things have definitely improved over the last couple of years. It's obviously hard to write and keep everything up to date, particularly with a small team working on it.

    I don't really have a preference for how Unity continues to improve documentation (internal or more open with public contributions etc.) but I will say that it is extremely hard trying to keep up with and learn new features and the API by reading release notes with one-liners describing changes, or blog post overviews, or beta google docs.

    In isolation, some areas lacking documentation in places would be ok - the release notes/beta google docs along with some personal r&d and experimentation, forums, answers, asset store/authors, dev blogs, and open-source stuff on GitHub etc. would help fill the gaps until the mainline docs caught up. The problem is that the gaps in the docs are generally a bit broader than this or things are out of date, so finding reliable documentation and technical info often requires a bit of looking around in all of those places and time guessing/experimenting/disassembling. eg. Editor scripting feels like it's nearly undocumented - I think I find useful tips and classes every time I casually browse some tool from the asset store or on GitHub. Often it feels like I've managed to trick Unity into doing something rather than reading about a feature and then implementing something with it properly.

    Thanks for explaining the current state of the documentation team, the scale of the problem, and your approach to improving things. Over the last couple of years the public and developer-facing parts of Unity have really improved - documentation, QA, and general communication.