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.
Examples (Score:5, Insightful)
Re:Examples (Score:5, Insightful)
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 (Score:4, Insightful)
Re: (Score:3)
In general, yes. But if you spend any time using larger APIs, examples of "how to do basic task X" become much more important. Examples of usage are a key part of any (large) API documentation.
For example, if the method foobar() in class Foo does what I want, how am I supposed to find it? Especially if the library has hundreds of classes spread across multiple namespaces.
Re:Examples (Score:5, Insightful)
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.
Re: (Score:3)
Re: (Score:3)
Re: (Score:2)
Re: (Score:3)
This JavaDocs - What Is? Never heard of it and don't run Java on my system but I have used QT Torrent, QT-Web, Firefox, Palemoon along with Notepad++ yet the quality of the docs tend to suck pretty badly. A good example is the Firefox Docs. They're online only and insist on trying to connect using Firefox only, which is a problem when Firefox is borked. QT-Web is a nice app but docs? What Docs? There's a few entries and FAQ pages but docs simply don't exist. QT Torrent suffers the same problem. It's more co
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.
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.
Re: (Score:2)
I'm reading Jules Verne and while a fascinating story it could be cut by 20,000 words of travelogue and could still use some pruning. That loquacious verbiage of the evacuation of core is just boring.
Re:In addition... (Score:5, Funny)
Documentation? (Score:5, Funny)
Real programmers don't document. If it was hard to write, it should be hard to understand. :-)
You youngsters always want things "explained" - geesh.
Seriously, get your hands dirty and work for it.
Re: (Score:2)
Documentation can make a standrd (Score:5, Insightful)
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: (Score:3, Interesting)
Re: (Score:3)
but his ideas were great, and no one can argue against it.
There are plenty of people who can argue against the design choices in C++, and plenty of people who think his ideas don't translate very well into large scale maintainable systems. He's made a huge computer to computer science, but that does not mean he hasn't made a few mistakes along the way.
No language is as dominant and most crucial to the world's infrastructure
Only if you are one of those people who refuse to acknoweldge the existence of C.
Re: (Score:2)
Re: (Score:2)
Late 80's I read about C++ and there were two thoughts that came to my mind simultaneously:
a) C++ is a wonderful language to write efficient, fast and comprehensive code.
b) C++ is a wonderful language to write extremely bloated, slow and unmaintainable code.
Take your pick.
Re: (Score:2)
Re: (Score:2)
"Unfortunately there are little choices (except C of course) if you want to write reasonably portable high performance code."
Sure there is. It's called Fortran. (Of course I mean at least Fortran 2003, and not some irrelevant ancient tome).
Re: (Score:2)
Not to mention that UNIX's 1st 'official' funding at bell labs was to develop TYPESETTING applications for DOCUMENTS
(see nroff - which is used to render man pages.. aka TFM of RTFM on a unix system)
Re:Documentation can make a standrd (Score:5, Insightful)
Re:Documentation can make a standrd (Score:5, Funny)
When I was in elementary I borrowed the first edition of K&R from dad's colleague. It's still sitting on my shelf.
It's your dad's colleague here, and I'm still waiting for you to return my damn book!. Kids these days, no respect.
If it ain't in writing (Score:5, Insightful)
Re: (Score:2)
It's a perfectly good tagline, one I've used myself many times. Though to be consistent,you should say "it don't exist".
Oh, crap, it's a wiki (Score:5, Insightful)
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 (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: (Score:3)
The problem is not when it's a wiki, but when there are only like 3 articles in it.
Re: (Score:2)
Oh, so horribly true. Especially when those three articles are incomplete, inaccurate, or years out of date.
Re: (Score:2)
As a tech writer, I've been fighting a losing battle against the wiki-docs approach for years. Nobody seems to grasp that Wikis undo a couple decades of progress in writing well-structured, process-driven docs. Confluence even pushes its own wiki as docs tool. Needless to say, documentation is the weak point in Confluence's otherwise excellent products.
The design-by-document approach just isn't going to fly in this age of minimalist organization and agile development.
Re: (Score:3, Insightful)
Re: (Score:3)
The design-by-document approach just isn't going to fly in this age of minimalist organization and agile development.
There is no reason why you can't write the documents first in agile development. You just can't finish the documentation before starting coding. You can write documentation of the next set of code to be written before writing it. Agile mixes well with extreme, test first programming. Do the documentation the same way. Write a bit of documentation; write the tests that match it; write the code to make the tests work. Repeat until finished. At that time, you will have complete documentation, a test sui
Re: (Score:2)
The design-by-document approach just isn't going to fly in this age of minimalist organization and agile development.
That's really too bad. At this point in my life/career, I'd rather be doing documentation than slapping some junk together that will need to be fixed two times over once it is in the users' hands just because of someone's arbitrary deadline.
Regarding the parent coment, I've seen way too many open source projects that use a wiki that is both very poorly structured and inadequately populated as a substitute for documentation/manual.
Re: (Score:2)
I have an interesting relationship with Agile. Such projects tend to be reluctant to hire me as a tech writer. They look at my resume, full of experience at big, bureaucratic organizations like Sun, and also at my gray hairs, and assume I'll never adapt to their more informal methods.
But in fact I find Agile pretty refreshing. I've sat through too many boring, endless meetings and seen too many projects fall victim to politics and Paralysis by Analysis not to see the merits of Agile. It's adaptive, it respo
Re: (Score:3)
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: (Score:3)
I once tried Inkscape and realized in disgust that the "manual" was a wiki.
No, it's not. What gave you that idea?
What you really need to try, though, are the Tutorials. They're under the Help menu and actually consist of SVG documents opened in a normal Inkscape window. It's simple yet brilliant -- when talking about a feature it simply suggests you try it there and then on that document. You should give it a try. Inkscape is an example of documentation done *right*!
More than a few assumptions here (Score:3)
The first assumption is that you're actually writing it for somebody else and not yourself. In many cases if you've scratched your own itch, then you're happy and any comments are notes to self, not documentation for others. The second assumption is that you could, that it's only a lack of willpower. To many people coding a piece of software makes the logic of it so apparently obvious that they don't understand why it needs documentation, at least not any that's useful to anyone with a black box understanding of the code. The third assumption is that they're not once bitten, twice shy from useless or even misleading documentation and just decided that the code is the ultimate truth of what the code does and don't want to make any external document that won't stay in sync.
Re: (Score:3)
1) If your software has been released to the public (i.e. because you released it to the public) the assumption is that you want others to use it. Elsewise, keep it on your hard drive and stop polluting sourceforge. Too many people it seems have the mentality that they can just share their own dog food and others will want to lick the bowl. The thought process is basically "well, I can't sell this, but if I just give it away, maybe it'll make me famous and lead to something big." It's just a really lazy form of greed and opportunism, and thank goodness it doesn't work.
By writing the code you've done all the work and throwing it out there costs nothing, in case someone finds it useful. Nothing more was implied nor guaranteed, did a rotten piece of source code you got from Sourceforge steal your girlfriend or run over your dog or something?
If you're not interested in docs, good for you, move along, the article does not apply to you as a reader of docs, only as a producer of code that nobody else wants to use.
Fair enough, if you're sure it's the documentation and not an awkward interface to poor code - I'd probably keep working on those two. Well working interfaces calling good code gets used, while a turd is still a turd even if you document
Documentation is just large form comments. (Score:5, Insightful)
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. (Score:4, Insightful)
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.
WTFM? (Score:3)
I wrote the fine code, YOU write the fine manual. Do I look like a tech writer? No, I do not. (They generally dress better but are more disheveled, which may have to do with the contents of their hip flask)
Re: (Score:3)
Fine, I'll write your manual for you. Shall we discuss money?
What, no money for docs? Never mind!
Re: (Score:3)
Tell you what, write the manual and get a 90% refund on the price of the free software you're using.
Re: (Score:2)
I was making a joke about the fact that commercial softwre projects rarely consider documentation a high priority. If you have an interesing Open Source project that needs a tech writer and dioesn't have the resources to pay one, I'd certainly consider donating a reasonable amount of my time.
Please open the box using the crowbar inside (Score:3)
Sure thing. However, before I start I'd better get completely familiar with your wonderful program in order to correctly explain it's operation, so I'll just have a good read of the manu... oh, wait...
Get a tech writer buddy (Score:5, Insightful)
Re:Get a tech writer buddy (Score:5, Insightful)
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.
Re:Get a tech writer buddy (Score:4, Interesting)
Re: (Score:2)
Never said that all English majors are technically deficient. And even the majority that are sometimes make good tech writers. But I've known a lot of really bad tech writers who thought their English degrees qualified them to write about anything, There are mental skills in tech writing that are a lot more important than the ability to interpret the metaphors of William Faulkner.
Re: (Score:2)
A good technical writer is worth his weight in gold. A bad technical writer is worse than just reading the header files/javadocs/whatever, and most are bad.
talk to your PC (Score:5, Insightful)
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.
Re: (Score:3)
That's a really interesting approach. Are there any examples of it in the wild? I'd be keen to see what one of these narratives looks like.
Re: (Score:2)
put a picture of your favorite gorgeous actress next to your PC, stare into her eyes, and describe your program to her.
Yeah, I'm just worried that my documentation of... software might end up x-rated.
(Though on a serious note, I've considered dictating before, and after your post I might actually just follow your advice and "Just do it.". Though I would try to correct the punctuation afterwards anyway.)
Three reasons (Score:4, Insightful)
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 (Score:5, Insightful)
Re: (Score:2)
A programmer does not have to be a good writer, but a good programmer is a person who has good organizational skills, someone who can write lists of topics and subtopics that the documentation should include. .. and in documentation.
A good programmer is also good at reading and spotting errors in code
Therefore, a programmer could very well cooperate with a professional writer, where the writer does not have to be a good programmer:
The programmer could start writing a terse, stilted documentation. The writer
Re: (Score:2)
It is very rare for a good programmer to be also a good writer.
Maybe - but if the programmer does not write any description of what he has done, then someone who is a good writer has no chance at all. So: when you write the code, write (in English/...) what it is trying to achieve, why it is doing it and how it fits in with other code/programs.
Even better: write the documentation first and then the code. There are times that I have done that, realised by trying to explain what it has to do that my spec was not quite right, fixed the spec and documentation - the code pr
Re: (Score:3)
Literate Programming - Write both as one source (Score:2)
Knuth's source for TeX and METAFONT does this (he created the technique to enable him to write the system).
I've found (re)writing a program as a literate program results in a much cleaner representation of the code and algorithms and a clearer, more understandable manual.
DEK has since written an entire book on the concept (_Literate Programming_ a CLSI series book) a decade ago, but one seldom sees source so provided.
There are some really cool example programs which're quite interesting (and educational) to
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: (Score:2)
You want me to write manuals? Pay me. (Score:3)
I am a freelancer, I am doing what the customer pays me for. I also write open source software in my free time. You don't like it? I don't care. I don't do it for you. I write it for me. I don't need a manual for my own code. So why do I publish my code at all? Why not? Maybe it is useful for someone. I just don't feel any obligation to make it useful for anyone but me.
Re:You want me to write manuals? Pay me. (Score:5, Insightful)
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.
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.
Adopt the Microsoft Press Model (Score:2)
Even if there is a FM ... (Score:2)
Both examples and explanation are needed.
Nobody has addressed the examples (Score:2)
And I'm not going to address the examples either. At least, not exactly. I use Google's Protocol Buffers in a project, and figured out how to use it from Google's documentation. Except I still haven't figure out how to use the ZeroCopy classes. The documentation is that bad. It's horrific. It exists, and tells you the first dozen things you need to know. Then it STOPS. And doesn't tell you anything else. I swear Google puts it up as a test. If you can figure out how to use it from their docs, you
Re: (Score:2)
Docs are for the trashbin of history (Score:2)
The forces that brought about written documentation were:
1. Computer RAM too small to hold a document, lack of multitasking (in DOS days), and lack of screen resolution/real estate (even pre-dual monitor days, which was only 2-5 years ago).
2. Release cycle of software was annual or longer, rather than automaticaly patched daily from the Internet.
None of those is true any longer. Software should be self-explanitory. And if it's not, there is now an alternative:
YouTube
It's fairly simple to run a screen capt
Re: (Score:2)
It starts with a website (Score:5, Insightful)
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.
"Get your documentation off my lawn!" (Score:5, Insightful)
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.
Docs are first thing I look at. (Score:3)
When I need to evaluate some new tech, be it an API, language, tool, or just about anything else, the first thing I look at is the documentation, after that I look at the community support. Because I know I'm going to get stuck at some point and I need to know that there will be a way out. Even if another tool will technically be a better fit for what I'm trying to do, I'll still give it a pass in favor of a tool that I know what it can and can't do.
Not that good docs are easy, they're not. They take lots of time, even for bad ones, but if you want to see adoption you need docs that include usage examples. This is primarily why Open Hardware companies have been growing like crazy while Radio Shack stagnates. They don't just sell a 555 timer, they provide dozens of free tutorials showing all the cool shit you can make with it.
Information Mapping (Score:4, Insightful)
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:
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 :)
Re: (Score:2)
How to get TFM Written (Score:2)
Almost every university has a technical writing department. Those students often need real-world projects for their classes.
Call the professors and ask them if they would like some real-world software for their students to document.
At my last job (Score:3)
So for anything I learned about the software we used I'd write up how-to guides. This got all the way up to the company president who asked how I did it. I told him that for anything I was learning about, I took notes and documented. If it was something I wrote, I made sure to comment, notes, and then create a quick guide for it.
We can all write. You just need to take the time to do so.
Re: (Score:3)
At our work everything is documented. For every process we have at least 27 different documents, all inacurate or out of date in slightly different but important ways. And of course, they are impossible to find when you need them.
Individually, I have managed to find a way around this mess with my own scripts: I just write a detailed usage description if the script is run without arguments, along with examples if the syntax is complex. Since the documentation is actually part of the script, it is always
Re: (Score:2)
And that's not the worst problem. (Score:3)
Here's a simple list that will keep any unfortunate enough to have to read your "documentation" from tearing their hair out. (I'm looking at you, Microsoft!).
1) Table of contents. Learn to love them.
2) Guess what kids?! Not everyone has immediate access to an internet connection all the time, so no, your cute little wiki page won't cut it as documentation for anything.
3) Index words. They require brains not automation.
4) Never, ever, under any circumstances whatsoever, discuss a function, property, or other programming language characteristic, no matter how obscure, without being more than ONE click away from a working code sample that demonstrates that function. Ever. Really. The concept is almost never the problem. Idiosyncratic syntax is.
5) All code samples should be as simple as possible, demonstrating ONLY the behaviour of the function, property or feature under discussion. Embedding your single 2 lines of demonstration in 50 lines of irrelevance only proves you know how to cut and paste.
6) Don't be lazy.
I don't blame them (Score:2)
Programmers avoid writing documentation, because documentation is hard. They just got done working, working to write the program, and that was hard work. Now it is time to do the job all over again, in a different language: English. Someone may say the program was harder. I say, only slightly.
As many have said before, good documentation summarizes not only what the program does, but why. The why part is new. You didn't have to program the why part, just the what part. The computer doesn't care why. So you d
All I need ... (Score:2)
I have to chuckle (Score:2)
Now, see, when I started screwing around with embedded Linux-based single-board computers, I had lots of questions and documentation was not aimed at the newbie. So, naturally, I asked a lot of questions. More often than not, my questions were answered by "did you try Google?" or more obnoxiously, "If I told you how to do X, you'd be standing on the shoulders of giants."
Ironically, I find that even in cases where publishing a book for newbies can be justified, once you're past the newbie stage there is ra
Video tutorials do not count as documentation! (Score:2)
I'm getting annoyed with video tutorials.
More and more often, when I search for documentation, I get links to videos, mostly YouTube videos. At best, these are inefficient; if you really need to explain details of the GUI, you should be able to do it with a few screenshots, but videos involve someone who is almost certainly not a professional voice actor reading technical information aloud, in a format that is difficult to review or index, and doesn't allow for copy-and-paste of URLs or command lines.
It's w
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: (Score:2)
I find this an odd point of view given Apple's considerable effort and waste to improve the "un-boxing experience."
Re: (Score:2)
To save waste? More like to increase profit.
Ah, yes, sorry I forgot to engage my ultra-cynical "all companies have a Machiavellian conspiracy going on" mode before posting. *eyeroll*
Re: (Score:2)
Not everything is an application that is ''obvious'' to use. If you are writing that AJAX application you need to know how to call the JQuery (or whatever) functions that do the work; for that you need a manual. I agree with Floopsy, a lot of FLOSS is let down by poor documentation, the programmer gets the job done and often has not got the interest to write documentation. The meme ''read the code'' is not always a good one, especially if the code has few comments or just says ''how'' rather than ''why''. A
Re: (Score:3)
" The meme ''read the code'' is not always a good one, especially if the code has few comments or just says ''how'' rather than ''why''."
"Comments lie. Code never lies" - Keith Doyle
Re: (Score:2)
Re: (Score:3)
Re: (Score:3)
'Nuff said.
Writing documentation is boring and tedious.
'Nuff said.
Maybe it is, but writing, say, a FOSS library and then not writing any documentation is the best way of ensuring hardly anybody ever uses your code. Not writing at least half way usable documentation is a bit like spending tons of money developing a product and then doing no marketing because marketing is 'boring', you won't sell very much product. I always gravitate toward APIs that are well documented even if they have fewer features. Basically if I can't get a simple non-trivial example working in about
Re: (Score:2)
Self fulfilling prophecy. People don't read them because they suck. They suck because people don't read them.
Re: (Score:2)
You use a debugger? Wuss.
Re: (Score:2, Funny)
any "developer" who uses more than a text editor, command line build tool such as make, and a compiler or interpreter, is a fucking pussy.
Re: (Score:2)