Search Unity

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

Documentation?

Discussion in 'General Discussion' started by BMRX, Apr 23, 2015.

  1. BMRX

    BMRX

    Joined:
    Nov 23, 2014
    Posts:
    51
    When will the documentation be brought up to speed? I'm constantly finding things that are not current. It's starting to get annoying.
     
  2. Ostwind

    Ostwind

    Joined:
    Mar 22, 2011
    Posts:
    2,766
  3. Andy-Touch

    Andy-Touch

    A Moon Shaped Bool Unity Technologies

    Joined:
    May 5, 2014
    Posts:
    1,005
    What have you found that is not current?
     
  4. KellyThomas

    KellyThomas

    Joined:
    Jul 1, 2012
    Posts:
    39
  5. Aurore

    Aurore

    Head of Learn Content Production Unity Technologies

    Joined:
    Aug 1, 2012
    Posts:
    3,104
    You know you can help us by reporting any missing/wrong/improvement straight to the docs team by reporting it as a bug.
     
  6. BMRX

    BMRX

    Joined:
    Nov 23, 2014
    Posts:
    51
    I figured it was common knowledge as a lot of the documentation seems to be referencing obsolete method's and more. Did not see a point in telling, I mean like. There is a lot missing there!

    The amount that is wrong is so widespread you can call it an epidemic. I believe you need to really go through it and do some quality control.
     
  7. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    @BMRX: as I'm sure you are aware really, we do check the docs periodically for out-of-date content. The main systemic problems that have afflicted the script reference have been:

    1. Code language translation (eg, examples only being available in one of the two languages)
    2. Obsolete property accessors that were removed in 5.0 (eg, MonoBehaviour.rigibody, Transform.audio, etc).
    3. General situations where the sample code has some kind of error that means you can't compile it exactly as it is written.

    Problem 1 is being addressed by the introduction of a new language translator and a few other infrastructure improvements. I am actually checking through the script ref now to address problems 2 and 3.

    In general, we do check the docs for known problems and we are always looking for new ways to improve the overall quality. However, if you have any specific suggestions for improvements then we would love to hear them.
     
    Graham-Dunnett and BMRX like this.
  8. BMRX

    BMRX

    Joined:
    Nov 23, 2014
    Posts:
    51

    I'll be sure to point out any and all I see from here on out, that said.
    Is the team understaffed? Certainly there are resources available for basic data entry. Unity 5 dropped like a month ago now? I know those doc's are large. But at the end of the day anyone worth their salt in basic typing should be able to do a few hundred entries if not more a day.
     
  9. angrypenguin

    angrypenguin

    Joined:
    Dec 29, 2011
    Posts:
    11,789
    What? No! It's not about typing, it's about knowing, understanding, and articulating the correct information. If someone was to just bang along making a modification every few minutes they'd need a 100% success rate (as opposed to a 99% success rate) to actually be improving the system - no typos, no misunderstood information, no out of date information, no ambiguous language, no plain old mistakes, etc. etc.

    Based on my own limited technical writing expertise I expect each change would realistically take somewhere in the vicinity of 30 to 60 minutes. Identify the issue -> come up with ways to improve it -> propose one as a solution -> have that checked by a domain expert -> write the update into the system -> QA the update -> publish it. Even if those steps take an average of 5 minutes each that's already more than half an hour.
     
    3agle, Ryiah, BMRX and 2 others like this.
  10. Kiwasi

    Kiwasi

    Joined:
    Dec 5, 2013
    Posts:
    16,379
    Totally agree with this. My day job has a lot of technical writing as well. Its not just about words per minute. Its words per minute from a skilled developer who knows the engine well enough to identify the problems and provide the correct solution.

    At one point I was provided with a secretary to help with the output of technical writing. It then became a case of me making mark ups by hand, then sending them to the secretary, then reviewing the documents line by line for typos once they came back. I pretty soon gave up on that idea, ultimately I type faster then I write. And passing the task on to a non technical person just complicated everything and delayed the issue.

    So now I occasionally use the secretary if I have to make field changes away from my computer. But that's about it.
     
    BMRX likes this.
  11. BMRX

    BMRX

    Joined:
    Nov 23, 2014
    Posts:
    51
    @angrypenguin and @BoredMormon thanks for your input, though I do not have that much experience with data entry what would do you mean they need to figure it out?

    They have changed the values, as such already know what they are they simply need to change them in the documentation.

    EX: GetComponent(); is now GetComponent<T>(); really. I don't see this taking more than a few seconds.
     
  12. Kiwasi

    Kiwasi

    Joined:
    Dec 5, 2013
    Posts:
    16,379
    This is a great example of where technical knowledge is needed. You'll need to download the standard assets from the asset store to access this name space.
     
  13. BMRX

    BMRX

    Joined:
    Nov 23, 2014
    Posts:
    51
    Yes I realized my mistake after wards... I had the assets downloaded but they were not in the same location.

    But this does not detract from the fact that the documentation is not current nor does it change the fact that editting the values really wont take that much time. (Refer to the example in post #11)
     
  14. landon912

    landon912

    Joined:
    Nov 8, 2011
    Posts:
    1,572
    Ok, well let's actually think for a second. Let's make some assumptions:

    500,000 pages of documentation
    30 second loading time for each page
    3 minutes to scan each page
    3 minutes to make a change; 1/4 will need this change

    That means:
    173 days of loading time
    1,041 days of scanning
    260 days of changes

    With an average 40 hour work week that'll take:

    One person 884 weeks to make this one small change.
    Which is 17 years!

    A 10 man/lady team, 88 weeks to make this one small change.
    Which is 1.6 years!
     
    Last edited: Apr 25, 2015
    Kiwasi likes this.
  15. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    I think the responses more or less sum up the issue: fixing docs isn't just a simple "data entry" task, at least not in the usual sense of typing in names and phone numbers or whatever. There are certainly examples of problems such as spelling mistakes which are easily identified with a quick visual check and are just as quickly fixed. However, more often, the process involves rewriting code, checking information by testing or consulting developers, etc. Although we don't really have anywhere near 500,000 pages of docs, the overall time to scan and fix issue does mount up.

    For example, I am currently checking for code samples in the script ref that don't compile. Test compiling reveals which samples have errors in them and those errors then need to be fixed. A lot of the errors have originated from samples that use the obsolete accessor properties (eg, transform.rigidbody, gameObject.audio, etc) that have now been removed. Although the fix is straightforward in these cases, it isn't simply a matter of find and replace to do the job properly, so the code does need some minor changes from a human. It's a similar story with replacing obsolete API or cases where the code translation is incorrect or unfavourable. The required code is not generally difficult to write but it does require some thought, looking up new API, etc. And once the code is written, it needs to be test compiled again, and committed to source control. Again, not a massive overhead in each individual case but it isn't simply a matter of a few seconds per fix and therefore a few hundred fixes per day.

    As regards the doc team being "understaffed", well naturally, we believe we are the most important team in the company and so we can never have enough staff ;-) We are certainly considering options for adding new people to the team. However, the main staffing issue recently was that two people who normally work on the docs were out of action due to serious illness for quite a large part of the 5.0 development period. This definitely set us back and we are still catching up to some extent. Obviously, we are hoping that such illnesses are not going to be a regular thing for us and that we can safely treat this situation as a one-off. Anyway, taking this particular setback into account, we believe we are still making satisfactory progress with the docs.
     
    angrypenguin, Kiwasi and landon912 like this.