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

Examples

[tomhath]

First provide some *working* examples. Then some real documentation (not Java Docs).

Re:Examples

[Gorath99]

And then keep both the examples and docs up to date, for god's sake! The only thing worse than no documentation is useless documentation.

Re:Examples

[cheesybagel]

Actually if it is an API we are talking about Javadocs work great. Examples are also nice. Real documentation? If the API cannot be understood just by reading the Javadocs then You Are Doing It Wrong! The API sucks.

Re:Examples

[TheRaven64]

Javadoc / doxygen style documentation is great for understanding the details. It is terrible for giving an overview. Look at the Cocoa documentation, for example. If you get all of the Headerdoc (Apple's doxygen equivalent) documentation, it comes to about 8,000 pages. You really, really, don't want to have to read all of that to know how to use the APIs - most people can't keep that much detail in their heads anyway. You want a few high-level overview documents that you can read in their entirety and then refer to the API documentation for reference.

For an open source example, look at LLVM. They have doxygen docs and they have some high-level subsystem docs (e.g. 'How to write an LLVM backend'). The bits that are the easiest to work with are the bits that have both.

Documentation can make a standrd

[xtal]

I consider it no accident that the defacto standard language C (aka, "portable assembler") has a lot to do with not only it being the language of choice for UNIX, but the fact that it was accompanied by one of the masterpieces of programming documentation - "The C Programming Language" - By K&R, who most know also designed and developed the language itself.

Your ideas are no good if they can't be communicated to others. Often, inability to communicate good ideas is more an indicator the ideas aren't that good, than the documentation is lacking.

Re:Documentation can make a standrd

[Ksevio]

K&R was a great documentation in the days where it worked best to have a book next to the keyboard - Just the function reference saved me plenty of time. I'd say a more modern equivalent is with PHP. Sure the language isn't that great - it has all sorts of weird quirks and inconsistencies- but the documentation is exceptional. Almost all of the pages have a good description, an example, links to related functions, and a comment area where other people can extend it. There's no way PHP would have become as popular with documentation like Java

If it ain't in writing

[k6mfw]

it doesn't exist. OK so a bad tagline but I've encountered so many devices, systems, etc. with no documentation. Now I can understand if someone throws together a contraption late at night, then have a few hours sleep, next morning they move on to their next gadget. However, I have little tolerance of people bragging of how great their thing is, everyone else's systems are inferior, etc, etc, etc but they have no paperwork. Or else they have tons and tons (but in PDF format to not cut down a huge forest) which basically is same as none existance because you will be dead of old age by the time you get through all that material. If they don't have much documentation then be honest about it. There are a lot of smart people that design and build neat stuff, their strengths are not in well written documents. That's when you bring in applications engineers and tech writers.

Oh, crap, it's a wiki

[Animats]

I once tried Inkscape and realized in disgust that the "manual" was a wiki.

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.

Re:Oh, crap, it's a wiki

[cheesybagel]

Wiki documentation can be great if the people editing the wiki aren't a bunch of morons. Make of that what you will.

Documentation is just large form comments.

[Anonymous Coward]

I've met quite a few coders who are disdainful of documentation, citing many of the reasons that coders give for being disdainful of comments. - It gets out of date quickly, there's a good chance it doesn't match the actual behavior, etc. "If I want to know what's going on, I have to read the code anyway, so what's the point?" There's also a very slight alpha-hacker subtext, with the philosophy of "if you can't read code, you're not worthy enough to be using this program in the first place". As well as the "works for me" viewpoint - the coder who wrote it doesn't need any documentation to understand it, so why is it necessary?

It's sometimes difficult to convince a coder that there are people out there who are competent, intelligent, successful people but who have no interest in plowing through 1000+ lines of code in order to find out which flag they should use to get .png output. To someone who gets a frisson of pleasure at deciphering a wall of obfuscated Perl, it's a foreign concept that there are people out there that have other things they'd rather be doing.

 

Re:Documentation is just large form comments.

[vlm]

There's also a very slight alpha-hacker subtext, with the philosophy of "if you can't read code, you're not worthy enough to be using this program in the first place"

Also the alpha hacker view of my code is like poetry, perfect, precise, crystal clear, and self documenting. Usually... not.

Get a tech writer buddy

[sandytaru]

Former English and journalism majors, who are not always the best programmers but are very very good at explaining how a program works (or ought to work), should be inside every IT company and department on the planet. When I'm not monitoring servers (e.g. watching paint dry), which is my formal job description, I'm writing down everything from internal business processes to how-to installation guides on software for specific networks. My happy place is about fifty pages deep in a Word file.

Re:Get a tech writer buddy

[fm6]

I'm appreciative of your positive comments about my profession, but you overstate the contribution of English and journalism types. There are indeed many good tech writers with that background, but there are also English types who drift into it because they can't get work doing anything else, and produce cruddy docs based on too-fancy prose styles and lack of serious interest in technology.

Many good technical writers have technical backgrounds. I myself am a college dropout who wanted to be a computer scientist but didn't have the intellectual chops for it. Others I've known have been retooled scientists, humanities professors, and MBA types. The one constant is that you need the ability to explain complicated ideas simply (for which traditional training in writing doesn't always prepare you), a certain amount of simple curiousity, and the ability to ask the right "stupid" questions.

BTW, anybody needs some APIs documented? User manuals? Installations guides? I get off my current assignment in about a month, If you have an interesing open-source project, I will consider donating some of my time.

talk to your PC

[Simonetta]

Get a simple microphone like the blue-tooth-like headsets. Beg, borrow, or steal a speech-to-text program. (there's one buried in newer versions of MS Word) Train it. (for the S2T program in Word, you read the first few chapters of 'The Wizard of Oz' from the display on the PC screen).
    Now open a text file for your speech to go into and the software (or whatever) that you are trying to document. Describe what is displayed on the screen. Pretend that there is a beautiful woman next to you who is totally fascinated in the smallest most exact details of your program, and is totally in love with the sound of your voice describing it to her. If this is too much of a stretch then put a picture of your favorite gorgeous actress next to your PC, stare into her eyes, and describe your program to her.
      When you have a long and detailed text file describing your software project, close it and attach it to your source. Do this even if it means putting the whole thing in one long comment block and pasting it to the end of your Main file.
    Ignore all sentence structure, punctuation, and grammar mistakes in the file. You'll go crazy trying to repair them and most of the people who be needing this documentation will be so happy to have *anything* that they will overlook all the sentence structure, punctuation, and grammar mistakes in the file.
    If you don't speak English well enough to make the speech-to-text comprehend your words then either get a native English speaker to do all the steps above or use a Speech-to-text program that works with your native language. (if there are no speech-to-text programs that works with your native language, quit your present job and form a company is that based solely on making and selling such a program. Make it open-source free and have some NGO or your local Ministry of Culture pick up the cost). The people who are going to be reading the documentation in order to understand your program will either use a PC-based language translation program on your text file or hire someone at minimum wage to read your file and to translate it into more-or-less English.

    Read everything written above and Just-eF'ing-Do-It. Don't tell anyone that you did it. Just slip your rambling text 'documentation' file into the final shipping product disk or Zip file and let it be your little secret.
    Believe me, everyone who buys or uses your software will be glad that you did this. If you get fired, then become a consultant and teach other companys how to do exactly the steps described above and make twice as much money that you were before at the dingbat cement-head company that fired you.
    Just do it. Remember, every major advance in computer science made in the past 30 years was at one time called 'the stupidest fucking thing that I've ever heard' by Bill Gates. Speaking documentation to your PC seems stupid, but it gets the docs created when nothing else seems to work quite as well.

Three reasons

[griego]

I can think of three reasons why nobody WTFM:

1. It's hard. Would you want to write a manual for Excel or 3ds Max? I wouldn't. Where to begin and how to organize it?
2. It's time consuming. Software is bigger than ever, at least on the desktop.
3. It's not sexy.

Different skill set

[Celarent Darii]

It is very rare for a good programmer to be also a good writer. Heck in any job it is rare to find someone with two good skill sets. Even with the two skill sets you often only have time to do something well. I would have to say though when then planets align and the good programmer is also a good writer, usually some sort of standard results from it, and lots of progress is made in the field. Also, some projects don't really warrant the time to make extensive documentation. I wrote tons of LISP code that never had much of documentation because it didn't really need it and simply got the job done. I'm sure many projects never get past the stage of documentation on a need to know basis.

It starts with a website

[Gadget_Guy]

The problem isn't just with manuals. It starts with a website. As a programmer, you might rely on other people to write your documentation but those people will never even learn your product without knowing what the hell it does.

I have lost track of the number of times that I have stumbled upon a project's website only to be confronted with a changelog rather than a description of the product. There have been some (mostly open source) programs where I have eventually left the site without ever finding out what the software was actually for.

Every webpage should have a short statement of what the project is designed to do, along with what OS it runs on. You don't have to be a great tech writer to do it, just imagine what a complete newbie would want to see the first time they happen across your site.

Don't assume that your audience are also programmers and you might just get people interested who can actually write your documentation for you.

Re:You want me to write manuals? Pay me.

[techno-vampire]

I just don't feel any obligation to make it useful for anyone but me.

I'm sorry to say it, but if that's the way you feel, there's very little chance that anybody will ever get any use out of your code. Most people are only interested in using programs, not in fighting their way through the code trying to learn how to use it and for many people, if it doesn't come with instructions on how to get it working, it's not worth installing. At one time, that was mostly a Windows attitude, but there are more and more Linux users today who expect at least a little documentation, and as time goes on, their numbers are only going to grow.

"Get your documentation off my lawn!"

[PolygamousRanchKid]

We used to put older programmers out to pasture writing documentation. Despite their cranky "Get off my lawn!" disposition, they were very good at it, like grandfathers telling a story:

"Children, let me tell you a story from a long time ago, in a far away place, about an associative array of function pointers . . . "

But now we lay off the older programmers.

And now we outsource the younger programmers, so they won't even get to be older programmers.

So there's your documentation for you, right there.

Information Mapping

[SplashMyBandit]

Most developers hate writing technical documentation, and when they do they organize it poorly. I was trained in the "Information Mapping" school of tech writing that is based on the psychological aspects of learning and human working memory. The Information Mapping style has numerous benefits:

• * the information you want to convey can be broken into seven types
• * information 'chunked' into parts that are easy for the reader to digest
• * documentation is designed that you can skip to the part you need without having read much of the rest of the documentation
• * it is easy for the writer as they simply follow the information mapping process, you don't have to think too hard to start writing, unlike when you try to write without any structure, and
• * the documentation that is produced has little prose, so is quick to relatively produce.

Once you have the basics of Information Mapping then as you grow you get better at quickly structuring everything as well as writing examples and unambiguous sentences that can help your learners to avoid many pitfalls.

So, I believe the premise of this thread is correct, many manuals either don't exist or are poor from a learning perspective. The most surprising thing I found when I learned Information Mapping (only takes a day to go through, since it is far easier than learning a programming language, and from then on it is just putting it in to practice) was how easy and effective it is. nb: I don't get kickbacks or anything from Info Mapping, it just happens to be the best and most time-efficient tech writing technique I've seen, so I hope me mentioning it helps someone else who wants to learn to be a great developer (which involves being a great communicator too).

ps: info mapping is about structure and content selection, unfortunately it doesn't help with my typing or (lazy) proof-reading :)