Re: Equal branch
- Posted by jimcbrown (admin) Jul 01, 2014
- 1738 views
Writing documentation for something should be easier than writing the code.
LOL ... that's a joke right?
No. I am of course not talking about documenting someone else's work. That's going backwards. First the documentation should be written and then it should be implemented. If one is too lazy to do both parts, he ought to the documentation part. The code can be written by someone else if the docs are any good.
Shawn Pringle
Writing technical documentation - especially for a layman/beginner's audience - is very hard and in fact qualifies as its own occupational specialty: http://www.bls.gov/ooh/media-and-communication/technical-writers.htm
I'll go as far as to assert that there exist people who have the technical skills to control a computer by programming it, but lack the communication/social skills to explain things clearly to others. I don't think I'm the only one who asserts this: http://www.bizjournals.com/cincinnati/blog/2013/07/tech-companies-want-to-hire-it-grads.html?page=all http://www.thefiscaltimes.com/Articles/2014/01/29/Surprising-Reason-College-Grads-Can-t-Get-Job http://business.time.com/2013/11/10/the-real-reason-new-college-grads-cant-get-hired/
So, no, in the general case, I don't believe it is easier to write good documentation than to code. In fact, I strongly suspect the opposite is true.
That said, the real reason I haven't documented anything yet is that I'm lazy. The documentation already exists - in the threads where the features were discussed. I simply need to copy and paste the widely dispersed pieces into a coherent whole and stick them in the right place.
Even if _tom or someone else ends up rewriting the whole thing (as he probably should), having the original developer's docs as a guide would probably be helpful.
Anyways, I just spent the past few days working with Hostwinds (the new host) and euphoric and a few others (RC gets a mention here) to get the site back online after the whole Burst.net issue lead to an unexpected outage. So I'm more or less tapped out for now.
Of course, if you really find this state of affairs really intolerable, you can always put the documentation into the branch yourself. Like I said, it's already documented on the forum (well, more or less) if you know where to look. And anything you write will mean less work for me to finish documenting later.
