WTFM: Write the Freaking Manual 299
theodp writes "Blogger Floopsy complains that he would love to RTFM, but can't do so if no one will WTFM. 'You spend hours, days, months, perhaps years refining your masterpiece,' Floopsy laments to creators of otherwise excellent programming language, framework, and projects. 'It is an expression of your life's work, heart and soul. Why, then, would you shortchange yourself by providing poor or no documentation for the rest of us?' One problem with new program languages, a wise CS instructor of mine noted in the early look-Ma-no-documentation days of C++, is that their creators are not typically professional writers and shy away from the effort it takes to produce even less-than-satisfactory manuals. But without these early efforts, he explained, the language or technology may never gain enough traction for the Big Dogs like O'Reilly to come in and write the professional-caliber books that are necessary for truly widespread adoption. So, how important is quality documentation to you as a creator or potential user of new technologies? And how useful do you find the documentation that tech giants like Google (Go), Twitter (Bootstrap), Facebook (iOS 6 Facebook Integration), Microsoft (Windows Store apps), and Apple (Create Apps for IOS 6) produce to promote their nascent technologies? Is it useful on its own, or do you have to turn to other 'store-bought' documentation to really understand how to get things done?"
In addition... (Score:5, Informative)
to WTFM, please oh please oh please stop writing flowery, circumlocutious prose.
Succinct... Precise... Concise...
Bullet points, short paragraphs, and simple descriptions are fine in most circumstances; this is not an expository writing project. I don't want to have to wade through your awful prose to decipher what the hell you're trying to say.
If I want to read a fucking story, I'll read a novel.
Where's the money? (Score:4, Informative)
A cynical answer is that even if the language or framework author/project head was a technical writer worth his or her salt, it makes more sense to write a book and sell it. Because asking money for the language (compiler/interpreter+libraries) itself is not going to fly in the flooded market of programming languages unless it is really really good and only very few of them are actually that good. Maybe not even then, because the price tag of non-zero value is poison for easy availability which is a must if you want someone to look into your project or language on his or her free time. With frameworks you might get more leeway but not much, especially not if you count on having a hobbyist/hacker community to flourish. Of course, getting someone like O'Reilly to greenlight your book about your own virtually-unknown language or framework might prove to be tad difficult too... Of course, if you're someone like Apple or Facebook or Microsoft or Google who offer a platform with sizable userbase with monetization prospects, this isn't really a problem.
And then there is the fact as noted in submission that writing a good manual takes a different skill set than designing and implementing a good programming language. If you don't have it, someone else has to take up that work if it's going to be of any use. And for that to happen, the language or project has to exist in some kind of usable, stable state long enough for those "outsiders" to actually study and learn how this thing actually works.
Which brings me to the last point. The really good books about a given programming language or framework give also "learned in real world use" insights about the pitfalls, deficiencies and suggested "usecases to avoid and the usecases to strive for" of the language which might only be discovered afterwards. This also might or might not be easier for someone who is not intimately knowledgeable with the inner workings of the language or framework by the virtue of being the one who created it. You kind of become blind for the real merits and sore spots in your own work, so to speak.
And fwiw, I actually have no problem with the idea of paying for a book to help me learn a language / framework I want to know how to use. I have even done that! I do, sometimes, lament the fact that online documentation is lacking because looking up things is usually easier on those than on dead tree (or PDF files simulating dead tree).
I do share some of the sentiments of TFA though. Most infuriating is when there's a "quick and easy tutorial"... which also doesn't cover very much beyond the simplest of use cases and then theres a very terse api reference. And virtually nothing in between. At that point I usually ask myself "do I really have to / want to (+ have time to) learn this thing, and is there a good book on it?"
Re:Great but (Score:5, Informative)
When will Apple write a manual for their damned devices?
What do you mean? Apple write manuals for their devices. They are available in PDF form on their website. They don't print the full manual and include it in the box any more to save on waste, instead just giving a brief quickstart guide, but the full manuals are still available. They are also available in iBooks.
Here's the (156 page) iPhone 5 manual, for example: http://manuals.info.apple.com/en_US/iphone_user_guide.pdf [apple.com]
Re:Oh, crap, it's a wiki (Score:4, Informative)
When I was working in aerospace, we would often write the manual first, then implement. This forces developers to deal with ugly problems cleanly, rather than having some elaborate after-the-fact explanation of how to work around some limitation.
I used to get paid to WTFMs. If there was a good functional specification for the hardware or software, I could have the first draft done about the same time the early testing started, and much of it was lifted from the specs. You don't have to see it working to describe what it is supposed to do.
If I had to WTFM for something with a bad spec or no spec, something that was being developed ad hoc ... it took a lot longer.
Re:Examples (Score:4, Informative)
JavaDocs are documentation that you include with java classes. They fill the same niche as sections 2 and 3 of the UNIX man pages.
If you've ever used perl POD documentation, they work kind of like that on a conceptual level.
This is all documentation aimed at programmers, of course, not application or system documentation. If you want to provide documentation for a java application, you generally don't do it with JavaDoc.