When will the documentation be brought up to speed? I’m constantly finding things that are not current. It’s starting to get annoying.
What have you found that is not current?
@Andy-Touch , Here is a minor issue I found the other day.
The screenshot says “Sleep velocity”, the text says “Sleep Threshold”
You know you can help us by reporting any missing/wrong/improvement straight to the docs team by reporting it as a bug.
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.
@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:
- Code language translation (eg, examples only being available in one of the two languages)
- Obsolete property accessors that were removed in 5.0 (eg, MonoBehaviour.rigibody, Transform.audio, etc).
- 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.
2 Likes
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.
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.
5 Likes
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.
1 Like
@angrypenguin and @Kiwasi 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(); really. I don’t see this taking more than a few seconds.
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.
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)
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!
1 Like
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.
3 Likes