WTFM: Write the Freaking Manual

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?"

Comments

and what does the kama sutra have to do with this?

[RobertLTux]

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

[menno_h]

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

[znigelz]

I second this post. K&R is the evolution of the C specification, and some versions of C compilers were written entirely from the book itself. C++ was developed in 1979, but not released to the public until 1983 (the year I was born, coincidence? I think not). Bjarne Stroustrup worked for Bell labs. Bell kept the official documentation, "The C++ Programming Language", under wraps until 1985. Wow, two whole years (though I'm sure too long for some of your old wizards). It is without question the best meta/template programming manual ever written.

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

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?

[MarkvW]

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

[sandytaru]

I actually started out a physics major in college, and drifted over into English because Honors Calculus II with Theory kicked my hiney. (All my own fault: I spent my labs spinning equations around the axis and looking at the pretty pictures instead of learning the math behind it.) Not all English majors are automatically technologically deficient, especially ones who opted for a rigorous science and technology curriculum for their electives. I somehow finished with a minor in botany, which did nothing to help me find a job but everything to help me understand lab science and its specialized jargon.