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?"
and what does the kama sutra have to do with this? (Score:4, Interesting)
Whenever i get a response of RTFM most of the time its either
1 WTFM first (or update it with the new changes)
2 The Kama Sutra covers the subject better
Challenge for the SlashMind locate a current (2.6*) copy of the Blender manual in PDF format.
Re:Oh, crap, it's a wiki (Score:5, Interesting)
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.
Also, this gives you a design plan that you can follow while coding.
Re:Documentation can make a standrd (Score:3, Interesting)
inability to communicate good ideas is more an indicator the ideas aren't that good
If you find his book too complicated, then check out Stroustrup's other book, "Programming Principles and Practice using C++", which is more like a high school text book. Or check out his amazing and simplistic site for the aggregation of information crucial to c++, http://www.stroustrup.com/C++.html [stroustrup.com]
He may not be the greatest writer, or the most congenial, but his ideas were great, and no one can argue against it. No language is as dominant and most crucial to the world's infrastructure, and his books (and his online material) are a great companion in your time of need.
Are you patient enough to teach another person? (Score:4, Interesting)
I'd love to work on a manual for something I'm really interested in, like Blender, but I doubt that any developer would have the patience to teach me what he knows--all the while trusting that I am going to complete what I set out to do.
It's a problem.
Re:Get a tech writer buddy (Score:4, Interesting)