Slashdot Mirror
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?"
'Nuff said.
Who the fuck cares? In my company we grind out 40 page outlines on the template for writing a document everyday. Any document that's 30 pages long, once you strip out the cover page, change history, authors, approvers, ToC and glossary it's 8 pages. And 4 of them are textual repeats of the flowcharts on the other 4 pages.
A manual? Dear lord, any manual more than 5 pages long no one will ever read and any manual less than 5 pages long, is irrelevant make work.
If you want something simple you don't program in C++. It's a convoluted mess of a language so of course no amount of documentation is going to solve that problem. Unfortunately there are little choices (except C of course) if you want to write reasonably portable high performance code.