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?"
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.
Any person using FTFY or editing my postings agrees to a US$50.00 charge
First provide some *working* examples. Then some real documentation (not Java Docs).
Besides, with GUI or AJAX interfaces applications no longer need manuals. I remember having a shelf of computer books next to my computer desk. both the shelf and desk are gone.
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.
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.
It must have been something you assimilated. . . .
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.
..don't panic
I'm pretty sure it's never been "freaking" unless you're one of those awkward persons who are in the mid-ground between wearing a tie and wearing sandals to work.
Meh, at least the 2.6 manual is up on the wiki. Though... it's not done yet.
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.
mfwright@batnet.com
In making a decision on whether or not to use a technology or one from a number of competing technologies, one criteria I use is does it have documentation and how good is it? In a professional environment where speed is important because of deadlines and budgets, not having good docs (which forces me to poke and prod myself to figure out what's going on) is a big negative. I find PHP to have top of the line documentation, Microsoft and MySQL above average but occasionally confusing or less than relevant documentation. Google is also uneven - sometimes it's very helpful, sometimes it's so convoluted that I spend hours just trying to figure what the they're talking about. Just my 2 cents.
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.
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.
Live today, because you never know what tomorrow brings
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.
If it is a language, then the minimal documentation is a reference manual - which comes out of the specifications. Syntax diagrams, with minimal examples of correct expressions. This document is not that hard to write, as long as the "developer" writes down what he is trying to do to meet the project specifications.
Without specifications, you don't know if there is an error or not... or even if the developer knows what he is doing.
The reference manual provides guidance on USING the language, though it may not say HOW to solve problems.
That is up to a different document, the reference guide - which includes small examples to illustrate various topics. THIS manual is much harder to write, as it usually requires some experience with the language to have something to make examples from.
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)
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.
Occasionally living proof of the Ballmer peak.
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.
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.
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.
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 read, for example:
Will Crowther's game Adventure - available here: http://sunburn.stanford.edu/~knuth/programs/advent .w.gz (with an offer of a $2.56 reward check if one can find a bug), or as a document to just read here: http://www.literateprogramming.com/adventure.pdf
Or a CWEB version of the RPN calculator for K&R's C Book: http://www.literateprogramming.com/krcwsamp.pdf
Sphinx of black quartz, judge my vow.
Heck, I can't even get techs to read the service manuals sometimes, how are you going to get end users to read them? All of our equipment use to have a place on the back, that held the manuals. I use to say I could slit the plastic wrapper that came on the manuals & drivers, slip a 10 dollar bill into the book, come back a year later & would have a better than 70% chance of finding the 10 dollar bill exactly where I left it! Now, our manuals come on PDF included with the drivers disk, plus a small "basic" book, and they still don't read them, even though with a PDF it is searchable.
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?"
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
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.
People only need manuals if the thing is hard to use.
If you have only one button that says "DO!" then nobody needs a manual.
Thank you. No, seriously. There wasn't even any notification on the device or the in the box to let me know that.
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.
3 page getting started guide, sell a 3 x £50 books instead of inculding a manual
I have come across many software projects where TFM is either a set of examples, none of which match what I am trying to do and lack sufficient explanation of the examples for them to be usefully extrapolated to other use cases, or a description of the syntax of the input files with no examples of how to use it (so the semantics of the input files are not explained).
Both examples and explanation are needed.
The real "Libtards" are the Libertarians!
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 get a prize.
(Though that theory turned out to be wrong. Google recruiter did call me, but her group declined to interview me further. No prize for me.)
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 capture on your laptop with its built-in microphone. It shows the typical run-through, or use case to use the technical term, which is enormously helpful for first-time users. If you can't handle that, then you'd better hope you gain a fan who spontaneously does it for you.
The creators don't actually give a fuck about documentation. They don't need it and if you need it, that is your problem, not theirs. Can't figure it out? New adopter? Tough shit, ask the "community" so you can be told "RTFM, n00b!". Then, you can try Google where you will find 5 pages of people asking the same question and getting either the same or no answer.
There is no "-1 offended" or "-1 you don't agree with me" mod options for a reason.
Writing a manual is somewhat tedious but still the easy part. Writing a manual that conveys information is a completely different beast and out of reach for 99% of programmers.
And even after you have managed to put together a good manual that conveys the information nicely, you will find that (1) few people will read it, (2) of those who do, few understand it and (3) the manual will not be kept up to date.
So what happens is that there's a token manual that contains random information in a useless form and nobody bothers to read. The customers of the system will improvise and when it fails, they will send their setup to you for troubleshooting, debugging and reimplementing.
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.
Not to go all Zed Shaw on you or anything but that is grade-A, freshly squeezed bullshit.
Coding is explaining to the computer what you want done in very exacting detail. "Programmers" who can't write an explanation of what their code does can't possibly be writing very good code either.
The programmer knows what the user needs to do (s/he'd damn well better), the programmer knows what the code s/he wrote does, the documentation follows from there. Sure, it may not be Shakespeare, but it will be well organized and tell the reader what they need to know.
I've initiated and maintain several large free software projects, and I agree wholeheartedly with the basic premise here: I think that software without documentation is close to useless, and I put huge amounts of effort into it.
But, let's be realistic here: it's a LOT of work. I can easily spend more time maintaining the documentation than the code. I consider it time well spent, but realize (as others have pointed out here) that it's a different kind of skill-set, which programmers don't always have.
The bottom line is that I would rather people release software than not release it a all. (close to useless != useless). Still, I wish more projects would take this issue more seriously.
*orders latte at Starbucks while checking messages on android*
*fires up ipad*
"Boy, a lot of this free stuff created and posted by people in their spare time kind of sucks! Maybe it's useful, but I can't figure out how to use it right away.
If they expect me to stick around, they need to do a whole lot better. Either do the kind of work that they aren't skilled at doing, or hire someone who's good at it! And I shouldn't have to pay O'Reilly or Manning for the manual that's supposed to come with the software.
My time is worth money, you know!"
*sips drink, surfs /., updates Facebook page*
*posts article on blog*
"That's my advice... maybe they'll thank me for it."
Use the source Luke
To save waste? More like to increase profit.
You are assuming the specifications make sense or are actually what the client wants which isn't necessarily the case.
Two great examples of documentation so good I learned how to use the tech: Ruby and Qt. Both had complete web tutorials/examples and excellent help web pages. I don't know if I would have bothered to learn either had their documentation not been so good.
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.
Schroedinger's Brexit: The UK is both in and out of the EU at the same time!
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.
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 :)
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.
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*
Documentation - I don't care where I've worked, it has always taken seat WAY in the back.
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.
ERROR
You didn't pay me, you give nothing in return, and you leech off of my work (which I tolerate because it doesn't harm me), yet you go and bitch about it??
You assume, that we all would write that stuff for *you*, and that we're all insecure attention whores who *need* the golden badge, the pat on the back, and the whole hip-hip hoo-fucking-ray...
We don't. Some people are still confident individuals.
I write my code for me and me alone. In fact, one of the main points is, that it gives me an advantage (evolutionary/otherwise).
If you want something, how about you first think what you can offer me, that has enough value, that I'd care about serving you with what is a part of my lifetime that I could enjoy with actually doing me good!
Do you now hate me and call me "asocial", because I don't want to serve *your* anti-social egocentric ass?
I've worked on projects where writing the documentation was far more entertaining, and less tedious, than dealing with the actual code.....
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.
Please do not read this sig. Thank you.
The source code is easily the best documentation, even on large projects. Working examples come next, followed by comments / docs in the code followed by external documentation. Writing the docs first is a good way to insure nobody uses them, because they will generally lie.
You use a debugger? Wuss.
Subject says it all
Real programmers, of this type, are NOT professionals of any way shape or form. They do NOT understand the basic concept of "standing on the shoulders of giants", configuration management, and design documentation control. Those who are presently trying to create an Engineering exam for a software specialty should be FORCED to WTFM, and then be audited and FINED for NOT WingTFM.
The problem with some commercial books is that they are just copies of the instructions we write when working for a tech giant.
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.
That this quip needs a smiley emoticon, and that some programmers take it to heart as a mantra is quite sad really.
It's right up there with that other one, 'The code is the documentation'. No it isn't, the code only shows HOW but not the WHY.
Sigh.
Get HR add the following to the new grad job description:
- 7 years of redhat enterprise linux version 6.3 / Solaris 12 / Windows Server 2012 RTFM experience
- 7 years of POWER7 / MP Xeon E5-4670 + Intel MIC RTFM experience
- 7 years of data hazard free MIMD C++ template intrinsic / offline jcode optimization RTFM experience
- 7 years of hadoop RTFM experience.
- 7 years of petabyte+ big data RTFM experience
- 7 years of legacy compatiblity assurance RTFM experience
- 7 years of APT / duqa / CEL / SIEM / RF site survey RTFM experience
This all boils down to basic issues. There are too many distractions in our lives, TV, Apps, Phones, McDonalds, Burger King, Fast Food, Work, Sleep, Pay Bills, Pay Taxes; Do this and do that; stay on hold whilst I waste 45 minutes of your life trying to sort out your utility bill and then these plebeians cut you off and it feels like life is just a game of the Board Game SNAKES and LADDERS https://en.wikipedia.org/wiki/Snakes_and_Ladders
To get anything done nowadays you have to literally shut yourself off. No TV, no phones, no facebook, no twitter, no kids annoying you. Truly you have to get rid of all distractions and have some quality time with yourself. That is the only way to write a manual and RTFM.
If you are writing that manual; do not consult other people as other developers will throw you a curve or throw a spanner in the works. Hence back to no distractions....... write out a draft in full and ignore everyone including your wife.
That is how you complete a cycle of action from start to finish. Once you have the full draft... editing comes later ;)
I hope that helps put some sanity back,
All cows eat grass!
C++ has got to be, from even its inception, one of the most thoroughly documented languages ever. Certainly after it was standardized documentation's been excellent. What do you mean?
Remember the three manuals -- The User's Guide, The Programmer's Guide, and the Reference Guide? They are all important. Mission critical. Kids that post "tutorials" on YouTube don't know where their dick is, and even less how to teach or explain something. Examples are fine but without real documentation a complex example is more like an archeological site to mine than a piece of shared experience. Writing good documentation may take as much effort as developing the product behind it, and even more to keep up to date. But that's the price to pay if you want to sell, if you want adoption.
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 didn't have to tell it. But the why part helps humans hoping to understand your program immensely. Maybe because once they know your intention, they can guess your method, and so the program reads faster.
Anyway, that's why writing can be hard, even though you just wrote the program. Writing is hard because before you can write clearly about something, you first have to think clearly about it. And while writing the program, much of what and why you were programming was half-known to your mind, the rest in your gut or subconcious.
As stated in one of the highest-rated books about writing, On Writing Well, by William Zinsser:
Why would I spend a bunch of time on user documentation when I don't know if anybody will actually want to use my project? But if I don't spend that time then it's a given that nobody will use it? Documentation needs to be a "conversation" between developers and users. A simple email to the project lead saying "how do I do X?" is probably enough to kick it off.
Have gnu, will travel.
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 rarely a good advanced text available.
Now, if you think undocumented technology is frustrating, try dealing with government bureaucracies and their inscrutable paperwork. I'm convinced that there are too many people on this planet who serve no other purpose than to generate extra crap the rest of us are forced to deal with for no other reason than to justify their own jobs.
Butterflies...
....on coffee mugs.
Fine. Phone Apple and tell them you will supply the paper (recycled of course) and toner for the manual and you want a copy. I'll await their response with baited breath.
This is interesting. I am more of a writer (and painter) than a programmer, but got a programming degree, because (in early '70's, seemed to make sense), because I wanted to avoid literary criticism. Anyhow, documentation is ALWAYS LACKING. You have programmers, and they are not, repeat, NOT, writers. Their own thinking does not naturally expand into every => man / woman's word / idea domain. And, I must say, I myself thought documentation in my own programs was a violation of the beauty of .. wondrous lines of code. Especially when they worked. Well, I am artiste. I do think tho', that WTFM is an honest and good addition to our lexicon. WTFM, you guys. I have a hard time in my old and disabled age, to understand, so please do so.
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 worse in my job, where for some reason, instead of actually writing out documentation, we get training videos recorded by project managers in which they talk over a Powerpoint presentation. At least there's the Powerpoint to refer to, but any additional explanations by the managers are difficult to hear, and again, difficult to review or index.
Really, what's so appealing about recording a video, instead of just writing out an explanation?
I find this an odd point of view given Apple's considerable effort and waste to improve the "un-boxing experience."
THREE.js is the worst example if this. the documentation is basically machine-generated API definitions with a "getFoo() - this method gets the foo" (sometimes) uselessly sprinkled therein. if you suggest that this could be improved, something that many people have tried, you will either told to:
a) go look at the samples
b) look at the (poorly commented) source code, work it out yourself
c) write the f'ing docs yourself
d) shut up
e) really shut up, shortly before getting banned
seriously, who tells a n00b that they should be the ones writing the docs?
The code shows the how and the why. There's nothing the code does that the code doesn't explain -- by definition.
You're just too bloody inexperienced (or possibly stupid, or lazy, or some combo thereof) to understand it.
You can't expect to understand code that you're not good enough to write. That should also be obvious. I'm talking to you, script kiddies.
Don't make the mistake of thinking a Wiki is a manual either. You're users won't write your documentation for you.
It's uncool to self-promote but I'm old [therefore uncool anyway] but that's exactly what I've done for every iteration of http://sourceforge.net/projects/cclite/ which is alternative currency and LETS software.
A few remarks about this:
1. I did tech writing for a computer manufacturer in the 1980s, so I had some previous experience, it's harder and more labour intensive than it looks.
2. If you have the manual, you have to update it for releases, otherwise it's getting bit-rot
3. Give it to someone else [preferably not deeply in your project] to read through
4. Give it to someone who is second-language English if the manual is in English [probably the best choice]
5. Give it to someone else to edit, if possible, my ex was a newspaper sub-editor
6. Read a grammar and style manual once anyway, Elements of Style and trawl through this: http://technicalwritingworld.com/forum/topics/list-of-books-every-technical
7. Plan the manual [by making a table of contents, for example] before you write it and use the heading hiearchy to give you a 'house style'
I can probably think of more, it's actually creative and fun, but it's not an easy thing to do well [and I'm OK but not the 'best of the best']. Like code the more you, the better it gets to be. Incidentally I spent a while with A5 so I could publish on Lulu as paperback size, but I've gone back to A4 currently, that's 'another' choice.
People do say 'hey there's a manual!' from time to time. Reward enough.
On y va, qui mal y pense!
The most important page on any site is the About page - people arrive with little clue on what your site or program is about, so it's incredibly valuable to provide the About page. Just a few paragraphs written without assuming previous knowledge is enough.
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...
In a survey of 100 programmers, 111111 thought that duck-typing was a good idea.
I concur. You can't copy/paste from YouTube and you can easily skip over a boring part or get back to the part you didn't understand properly or bookmark a page for reference. Code snippets are impossible in a video and generally you lose interest when you realize that your documentation is narrated by a 14 year old.
P.S. Tutorials are not a replacement for proper documentation. They are usually both needed - tutorials to show you what it's all about and whether or not you fill find a use for it, and documentation for reference.
As a programmer, senior member of the Society for Technical Communication (STC) and user of software, I've accumulated some ideas about what works.
The primary factor is design. Before any coding is done, there should be design. It's the same for movie producers, authors, web designers and people who make products in the physical world. Start with a storyboard before anyone touches a computer. Think like a user. Think like Apple. You want a fantastic design before coding.
What is Design? Of course it is about accomplishing some task efficiently. It's about speed, CPU consumption, storage & memory requirements. But referring to the user and documentation, it's mostly about the User Interface.
If you're updating legacy software your job can be more difficult. Existing users will complain about any change, but if you come up with a fantastic user interface that uses the same data sets, they'll get over it.
If you're programming esoteric stuff like a disk operating system (please do, we need something badly), nobody but a few engineers will see it so documentation is easy- they speak your language.
Test every step of the way with input from potential users. Adjust, but always with the Design in mind. Users should instinctively know how to achieve their goals with your software. I'm not talking about Mathematica, Autocad or C++ here, but everyday software used at home and in business. (I do have a gripe with Autocad, however, for taking so long to improve their user interface while others had to show the way.)
In many cases, if you did it right, no documentation will be necessary (Just the required safety warnings, FCC and other regulatory comments, patent, trademark and copyright notices, warranty limitations, etc (barely 20 pages). If you didn't do it right, you can hire one of the thousands of professional technical communicators around the world to make learning it tolerable for users.
...omphaloskepsis often...
There are a couple of approaches to software documentation.
1. Descriptive (broad focus). Explain to the user what the program is for. Explain the concepts you use. Why do things work as they do?
2. Task oriented. Explain to the user how to perform tasks, e.g. How to set up a compound interest calculation in a spreadsheet. This pulls different elements of the UI together and puts them in context. Useful for the novice, but always lacks some detail the advanced user needs.
Skip the trivial ones, depending on your audience.
3. Descriptive with a narrow focus. Sescribe what each element of the user interface does. Helpful as a reference, but not much use to a novice. Man pages are like this.
You'll find that a good manual combines all three approaches (in the above order).
Start writing the manual as early as possible. Use it as part of the software specification process. Then compare the manual and spec to the program: does it work as advertised? If you find that a task is hard to explain or contains more steps than necessary, it's time to improve the user interface.
Involve non-programmers in the manual writing and testing process. They look at the software differently to a programmer. As the creator of a program, you take lots of things for granted that are non-obvious to a user. Find out what these are and either explain them in the manual or (better) redesign your program so you won't need to explain as much.
hackertourist
(technical writer)
First provide some unit tests and regression tests that run under continuous integration. Then some real documentation (not Java Docs).
FTFY.
Continuous integration assumes a waterfall development methodology, which is a great idea if you are building a prototype, and a terrible idea if you are building a product.
The reason this is true is that the continuous integration and waterfall models do not lend themselves to productization, which requires a feature cutoff and a feature focus. If you are doing either, you aren't feature-focused, since the development is scattered over product feature areas. What this means is that you don't get work on incomplete features prioritized. You can do a release cycle cut with your current top of tree, but you can't omit work intended for the next release cycle, and you can't omit partial implementation.
Unit tests and regression tests are a great idea, particularly if you are writing the tests first from a design specification, and only assigning significance to the test results after the design point is feature complete. If you are doing anything else with them, however, you are doing it wrong: you will end up with spotty test coverage, spurious tree closures on false/erroneous test failures, and worst of all, you will assign inflated significance to the tests you have in hand, vs. the ones you should have had in hand before you started your feature work.
There are some projects that get away with this model; Android is one of them. But they only get away with it because the cell phone vendors take a tree snapshot, and refuse to take additional waterfall work into their product after it has been declared feature complete, and then only do bug fixes. This process is called variously "integration" or "productization", and it's done by companies like Motorola, Nokia, Samsun, Ericsson, and so on, and it typically not part of the Android process proper(*).
(*) This, incidentally, is a partial explanation of why cell phone vendors tend to stick on antique versions of Android once the product has shipped, and do not issue updates. The rest of the explanation is the carrier business model doesn't actually want the updates, even if it were not effectively the same cost as developing an entirely new phone, as far as the handset vendors are concerned. To the carriers, changing this means that someone can get the new OS features and applications written for the new OS, and "ride out" the remainder of their carrier contract and switch carriers, rather than re-upping with the same carrier 6 months before contract expiration in order to get the new OS with the new handset.
I doubt it. I bought Final Cut Express some years ago (student price, very cheap) and it came with printed manuals. These things were about 90% of the volume of the box and, between the two of them, over 1,000 pages long. They also had PDF versions on the install DVD. I referred to the PDFs regularly. I don't think I opened the paper copy more than once. I expect my usage was pretty typical. Of course, it also increases profit, but increasing profit by not wasting paper and energy printing and shipping something that most customers will never read sounds fine to me, just as I have no issue with the shop near me that increases its profit by stocking food I want to buy...
I am TheRaven on Soylent News
If you wish to create an on-line reference then fine. OTOH understanding is about context and appropriate use. A function reference tells how to use it not why. A discussion of say various ways of doing something may introduce all sorts of concepts and easily mention useful functions or sections of the manual to look at in more detail but it is about why and doesn't need to be on a screen - in fact I would say it is better to have the why and overview documentation in a form suitable for picking up and putting down when the reader is in the mood for a bit of learning and not trying to look at the instructions while driving.
The real problem in documenting is why teachers have to spend 4 years in school to teach subjects they already passed the exam on years or even decades ago. Teaching is HARD.
Because IT IS NOT HARD TO WRITE for YOU. If I write an application or design a user interface or build a tool or design a game, then I know what I am doing, know what needs to be done and how to do it. To then switch myself into your mindset (arrrrgh! the HORROR!) and see my application with your limitted skillset, dimwitted logic and bad breath, well, that is hard. That is why ex-teachers are so welcome in IT to do training because they are trained to train people. And training adults after training 6 year olds is marginally easier because you are allowed to hit adults.
Writing good teaching material (and that is what a manual is) is hard because you need to add just enough information to fill the gaps in the readers knowledge, without flooding them with stuff they already know causing them to skip RTFM and missing the information they do need to know.
Doesn't help that the average user is a self-entitled prick with the attention span of a gnat. Writing manuals is a skill all in itself and one few are willing to pay for.
You want to RTFM? Pay someone to WTFM.
MMO Quests are like orgasms:
You may solo them, I prefer them in a group.
Do it yesterday.
It shouldn't. But it does.
Documentation is something you will do tomorrow, if you have time. You never have.
MMO Quests are like orgasms:
You may solo them, I prefer them in a group.
Seems most software these days doesn't come with documentation or support. They write a program, sell it and then set up a forum so other users can help each other figure out how to work around their bugs and shortcomings.
As an open source developper, I used to get a lot of negative feedback on the documentation, on how it was poorly written, lacking and generally unhelpful. This got me to make the decision to write a real manual, which users of the software could use as a reference, which would bring answers to (most of) their questions and allow them to become sufficiently proficient in the software APIs and features.
What I hadn't realized was how long it would take: it took me 3 months to write a user's manual from scratch. During that time, I completely stopped writing code for the project, apart from bug fixing. I tried to apply what I thought a usable manual should be like, including navigation, code samples and links to relevant code documentation. It was one of the most frustrating time in my life, knowing that I shouldn't go back to coding because it would give me an excuse to stop writing the documentation.
The rewards came when this work was completed. All of a sudden, the project was able to mention an actual documentation without shame. We are able to answer many of the questions in the user forums by providing the relevant documentation link. We could also see an increase in the proficiency of our users, as they were asking more technically difficult questions, asking for features they wouldn't have thought about otherwise, and making suggestions on features we (the project team) had overlooked. This also transformed the feedback we received about the documentation itself, in a complete u-turn from what we got previously.
This turned out to be a win-win, both for the project team and for our users. Now, updating the documentation to keep up with the latest version of the software has been integrated into the development process. A feature or enhancement is not considered complete until it has been fully documented and tested.
My 2 cents.
i.e.
The easier it is to do the more likely it will get done and it's important it should only be done once.
Document in a wiki markup format. Not html, something you can read and write easily as ascii, or utf8 these days but which can be up loaded to a document server, something like twiki is ideal.
Write a document maker, this is just something which will pull documentation together into a coherent whole. There are a plenty of tools which do this for specific languages but most are language specific, like javadoc or python docs. The most general purpose one and earliest example I've found is robodoc. Having said that I decided instead to go with a trivial shell script which would search down a directory hierarchy, cat any readme files it found and greps for a specific tag in text files. I'd have posted it here but Slashdot says it's lame.
Put it in your make files so you can simply type "make" and get some up to date documentation in the top level directory. I've now got an easy to use documentation framework, it gives me web documentation, it gives me application, function and configuration documentation, it gives me READMEs on the usage of specific modules. It's written in twiki format so it's easy to read as ascii or as a web page and I only ever have to write any particular part of it once and it's automatically included.
Perfect? Not by any means but it's easy, works and anything which allows # comments can be documented.
I blame GitHub and BitBucket for a lot of this these days. I can't even count the number of times I've read a blurb about an interesting project on someone's blog only to click a GitHub link and find myself staring at a minimal readme. No explanation of what I'd use the project for, no screen shots, no samples, no useful anything to tell me if it's worth while to dig into the source.
Do you mean Blender as in the 3D software? Forget it. The Blender team rebuilds the interface from scratch every six months. Any attempt at thorough documentation would be obsolete before it was half-finished. I know, I used to try to publish tutorials for Blender. Three months later, everybody's crying at me because they can't follow the instructions anymore - that button moved, this pull-down menu doesn't have that option, that shortcut key option changed. I gave up trying to keep up with Blender myself. It's not software, it's a cult.
Maybe it's a glamour thing too. "Hey, I wrote this cool app" gives you "Awesome!" as reply. "Hey, I wrote this excellent documentation" might just lead to [crickets.wav].
'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 2-3 hours due to lousy documentation I'll start looking for alternatives. I'm not going to rifle through sources to figure out how to use an API unless I am forced to.
Only to idiots, are orders laws.
-- Henning von Tresckow
In this particular case, the two are indistinguishable.
I've found the Apple IOS and Objective C docs to be fantastic - well organized, with search, examples, and you can link to them in your code by clicking on a method call. And if you want a tutorial, Stanford has FREE iTunes courses about programming for IOS.
Those folks who write documentation for a living know all to well that when there is an economic downturn, those individual who write documentation or gather requirements are the first ones on the financial chopping block. Management is always looking to slash budgets, and they see people who write documents as non-essential to projects. In the end, they prove to be invaluable.
I used to work for a company that was converting there efforts in a Brick and Mortar solution to increasing their market reach, but to do so they were required to have all departments have documentation up to a CMMI Level 2, and in one year of their pursuit they established a Brick and Mortar solution. This company is steadily gaining market value and shares and they do it in part due to extremely good documentation.
Good Documentation is one of the key reasons the Space Race in the 60's was so vastly successful. They documented everything.
Life takes interesting turns, but the most interest is when you're off the beaten path.
1 in when writing the code always try to put needed libs for a compile in a logical place (hint where it gets normally installed would be good)
or if you have to put them somewhere odd then dump a directory listing into a file and build the docs from that. (Hi to marc from the MakeHuman project)
2 make the builtin defaults the most common action to cut down on the number of CL flags needed
(an archive tool should Compress a list of files/folder to a file named after the folder its in and Decompress (to a new folder) any archives it is passed as an argument. as an example)
3 in all things be discoverable (ballon tips and proper labels are very nifty
4 HAVE A LOCAL COPY OF THE DOCS INSTALLED WITH THE PROGRAM not everybody has a 24/7/52 internet connection.
5 use Video as little as possible in your docs (and for the Love of The Divine Please do a proper job in making the video a 20 second task should not have a 15 minute video because you rambled on about "stuff") and post the Script for your videos so folks can download your docs.
Any person using FTFY or editing my postings agrees to a US$50.00 charge
Also don't forget to have at least one other assistant with some graphics skills, particularly that in typography and desktop publishing. Not just as one more set of eyes for proofreading, but to improve legibility in layout of the document in other ways. (Particularly true if it gets printed on dead trees.) There's nothing like weird page breaks, orphan text, incorrect chapter/section/index information and page numbering, or poorly aligned or misplaced tables or illustrations, which can make otherwise well written documentation look very sloppy and amateurish and harder to follow than it should be.
Yes, it's more work going from Word to InDesign (or Libre Office to Scribus) and doing it right, but it's well worth it when the .pdf actually looks good. Nicely planned layout and good publishing practices also the reason why people are willing to pay money for Peachpit or O'Reilly books, even when similar information can be found for free.
Agree or disagree, modding this as troll is so inexplicable, it spurred me to metamod.
One sees WTFM a lot. It is usually said by people who do not have the time to understand and respond to user questions about the material they are reading in the manual. The WTFM attitude in "user forums" that companies deploy to replace staff help desks is one reason for me to reject the product as unsupported. When I investigate a product I do check on what assistance is available. It is amazing to me how few companies provide good support to their users. I have even read company staff posts that belittle product users when they do not understand something. Another thing I have found is that good companies with solid documentation and user support sometimes get bought out by larger companies who then treat the purchased company as a cash cow. As a result, documentation and support dry up. I have dropped products as a result of this behavior. I guess some companies actually believe their product is so unique that there are no alternatives. Such is never the case. Although worthy alternatives take time to find, they are available.
Sometimes documentation is difficult to write because the concepts explored by the software are difficult to explain in terms other than rewriting the code as English algorithm descriptions, which aren't particularly helpful.
My documentation for MSS Code Factory is such a case. I've provided high-level documentation of the GEL syntax and underlying object hierarchies, but to actually apply that knowledge you need to get your hands dirty and play with the tool. There is no concise way to explain how to use it, but there are thousands of lines of examples showing you what to do to make it go.
The basic input itself (the XML Business Application Model format) is particularly terse on the documentation, because it's intended for use by someone who'd want to integrate the tool with an existing design or UML GUI, or who's willing to write raw XML. It's not a "pretty" tool with a GUI interface, and the lack of a GUI puts a lot of people off.
But the goal of the system never was to write a GUI. It was to provide a back end code manufacturing tool that could be integrated to existing projects that already tackle the work of a GUI. Maybe some day I'll have time to work on a GUI, but if anyone is waiting for that to happen, they may as well give up on my tool because that won't be happening for a year or few.
I do not fail; I succeed at finding out what does not work.
Take tor for example. I'm interested in secure and/or anonymous surfing, but have no particular need for it at present. I recently thought it might be fun to throw tor on a machine and try it out. It soon became More-Trouble-Than-It-Was-Worth. Documentation was horrible, but so was the ease-of-use. The product needed more usability improvements than it needed better documentation, but it needed that too. It's been my experience that just about any product that includes encryption is suffering from a major handicap. I know there's no such thing as "painless" encryption, but if non-techie nerds are ever to use it, it must be comprehensible, and far easier than it currently is to use. And bad documentation is not a good start-- good documentation will help show you where the product needs usability improvements.
Support for many kinds of products has all but evaporated in recent times. Whether in the form of software documentation, product warranties, or parts availability, the trend is trim any function or service that doesn't generate a direct profit. We are encouraged to think of products as black boxes, and when they don't work, well just don't hold it that way.
There's no way, other than just replicating the entire bloody thing verbatim, to define and format a decent man page with the given tools.
You have to write after reading what needs to be IN the man page what is to be put in the man page. Worse, much of this is actually duplicated (or triplicated or quadriplcated) from elsewhere and you have to ensure they are all synched.
Take the options for a start.
There's the synopsis which needs the options written down for use in the man page. There's the usage line for a "-h" help option on the command line which needs the same information in it. Then you need to pass this on to getopt (or ArgParse, or whatever new and improved(tm) option parsing script you have in your system) in another format to parse those options again.
Change one, change all.
But the name of the program and purpose? You have to write that in as a man page section AND as maybe the docstring (in python) so that the IDEs can pick it up. Duplicated info again. Several people (including myself) have written scripts to try and improve this situation for our workplace, but nothing package-supported results.
There's no definition of how to assert the sections in the man page like examples. Or "See Also". And so you have to write this info out as a specific step.
But if you write it in the given paradigm of Sphinx or POD or whatever, then you cannot integrate your attempt to keep the getopt options, help and synopsis set in one place included. I.e. you either write the entire thing out or "roll your own" process, duplicated and error prone effort for whose benefit?
And users are pretty crap at telling you what they need. They're better at telling you what they don't need, but any time you get a half dozen of them to ask for features, you'll find every point pretty much has two contradicting requirements from different people.
They more often agree on what they don't want.
There are some prinicpals for real good documentation. My list my not be complete (so do not hessitate to add points), but as a starter:
* Documentation should explain why someting is not how. The how is part of the source code and its inline commentary. Example:
While the interface FileAccess may have the followin form:
public interface FileAccess {
public void open(String filename, FileOptions options);
public byte buffer[] read(int size, int records);
public void write (byte buffer[]);
public void seek (int position);
public void close();
}
There should also be a note that, you only can read/write if the FileOptions object set the flag for read/write. Furthermore, the language the interfaces speaks is: (open,(read,write,seek)*,close)* so read before open is an error. This is the documentation of the interface on code level. However, the documentation why it is, is missing. While it might be obvious what a file access interface does (because you know or think you know the domain of FileAccess), it is still required to describe the why and the domain as such.
* Documentation (especially design documentation) should be written before coding. Documentation written by coders after they completed their work, normally just describes what it does, and the context, domain and the why is missing. If you do not know what to write in the documentation, you are not through with solving the puzzle you try to implement.
* Fix documentation after the implementation. Humans tend to forget something, which they find out writing the code. Add that stuff to the documentation.
* Your documentation should start with a requirement or a feature of a requirement and be traceable to your code fragment.
* Documentation should state which concepts are used. For example: if you use a factory, call it a factory, tell in the documentation why you used a factory and what domain it belongs to.
* Do not bloat your documentation with bla bla, in many cases a bullet list is much more helpful than two or more paragraphs of continuous text.
I'm a programmer, but also a writer. I'd love to be a technical writer, but don't know where to start. I'd love to build a career out of - oh, wait, no one will pay for technical writing. I tried writing a technical book in the late 90s, and made pennies per hour. I think I would have made more collecting scrap metal from people's recycle bins. I'd love to volunteer for ... something. All the obvious things have books already, because I have read them. There's already enough books on C++, Linux, Python, Android, etc to build a wall the size of the Hoover dam. There are a lot of exotic technologies I don't understand that I won't be writing about. So just point me to where I can start, and I'll be writing. You do want LaTeX source, right? No? HTML? No? Wiki - you're not serious.
Agreed.
I teach web design at a technical college -- have been doing so for twelve years -- and I can affirm, from considerable personal experience, that the effort involved in writing lectures notes (documentation) for other people is profoundly easy to underestimate, profoundly difficult to get right.
Writing for oneself, it's easy to believe that one's writing is effective.
Writing for others? For a mixed audience of semi-technical and non-technical laymen? That is tricky: in my experience, writing for anyone other than myself is usually more difficult (and time-consuming) than I expect.
-kgj
Whoa dude, better pump the breaks ... Unreal Engine 3 is a rockin' fine gaming engine!
... Except when the editor crashes during lighting compile ... then it's a piece of worthless shit, indeed.
But when it's great, it's great! Check out my maps: handyvandal.com.
-kgj
I'm learning to use Twitter Bootstrap, and the documentation is really sparse, so I turn to Google to find me other people's examples of, in my case, how to implement site menus.
The biggest problem I find is companies that jump from "here's how to install the software" to "here's an exhaustive list of all the functions", and a few sample apps, without delving into conceptual issues like architecture or implementation. This is where the O'Reilly style documentation helps, as they step through the product conceptually rather than the functions alphabetically.
My favorite line about documentation, stolen from the front page of the gawk manual:
"Write documentation as if whoever reads it is a violent psychopath who knows where you live."
I find this an odd point of view given Apple's considerable effort and waste to improve the "un-boxing experience."
What waste in that context? They have spent the last few years steadily reducing the packaging of each product while still attempting to maintain the "experience".
Every product they produce has had the packaging reduce in size and complexity and increase in ease of recycling. They have virtually eliminated (but not entirely in some products) expanded polystyrene and they have reduced the wasted volume where possible to decrease shipping costs.
What waste are you referring to?
I have been reading a book "Beginning Drupal" by Wrox press. Its supposed to be for version 7. ITS A JOKE! They went to press about 18 months before Drupal 7 was in feature freeze. As a result, when it says 'click here' they really mean 'fill in that box that we aren't telling you about, click that other button that we aren't telling you about, and then a new screen comes up, some of which we will tell you about. Its also all about code examples that simply don't work (perhaps they worked in a previous version?). Debugging this book has been a bitch (and I'm 17 chapters in, and have lots of notes on nearly every page). Worse, there are syntax and grammar issues in the written text! The errata for this book is 2 paragraphs. Its worse than a joke! It points out one of the problems of OSS/FOSS. Since things are sometimes moving so quickly, documentation is almost impossible because things change faster than the documents can keep up (although in this case, they jumped the gun and screwed up royally). I try not to buy documentation in hard copy form if I can help it. Its easier to delete/toss a CD or pdf.
Writing specs and manuals is fun and useful. You might even call it The Joy of Specs.
Are you kidding me? The packaging for most Apple devices is as minimal as you would wish. Compare, pound for pound, the amount of packing, plastic, manuals, and other crap you get with a typical phone, laptop, or PC, and you'll find that Apple manages, in all cases, to do more, with less, than any other manufacturer. Examples follow:
iphone packaging
macbook air packaging
Whether it is Microsoft's inability to write anything coherent or touch on anything but the simplest tasks,
or IBM's inability to correctly identify or link to the types of information available on their website
or Apple's absurdities with documenting or not documenting anything of value, especially when they put out a new version of software or APIs...
Java-related firms, especially Spring Source and the JSF people are crap-tacular as well.
No, they've proven that no one knows how to document. Or if someone does, they're keeping it to themselves.
Just as with any other venture, these companies get away with as little cost as possible. "support" for developers or users are forums - and there are some good forums/moderators/admins/support people on them.
With software it is usually even worse: the comments about alpha-geek status are true for a couple different reasons. Linux is a great example of no documentation - that's a reason why the last decade has been spent making it user-usable. Because they didn't want to create a manual that is good for that single version (and would be what, 10,000 pages?).
Too many times when someone does document something - whether book, forum, blog, etc. - they don't give enough context: VERSION OF THE SOFTWARE is the most key part almost always missing. Date of posts is also very important yet rarely included. Larger context...
And it is always a balance of covering the generalities or covering the specifics: do you want to know how it works or how to use it?
I think video games set the pace: they gave up on including manuals (typically altogether) to let book publishers create and sell more products. In a way this makes a lot of sense, especially when the UI/game complexity began to outstrip the ability of a single person to aggregate and correlate all that data. And video games typically have simpler UIs and interact with less other systems than most software...
YMMV, but I'm looking for the Documentation's One True Solution. Anyone have it?
8-PP
The new way:
Write the specs, manuals and test docs in parallel with the code, using the same versioning methods. Put dates and version numbers (not neccessarily the same as the code) on all documents, manuals and specs. Include them in the version-control systems.
Leaving the manuals for last is hopelessly outdated. ;-)
When I first dove into Linux, I would ask quesions on the various forums. The answer would always come back:
"Thats simple. All you have to do is...... (now the answer rockets into noob incomprehensible land)"
Then if I were to ask for a clarification or further explanation, the person answering would get frustrated, and some times a little angry. And I noticed that happening a lot, not just with me.
So yes, I was a noob, yes I had a lot to learn, but I did eventually learn, but mostly on my own. And after learning, it was obvious that the people who originally tried to help were just really bad at communicating.
So it's almost like if you are going to provide a comprehensible manual, you'll have to have a trained commuinicator on the job too.
The shepherds did so well protecting the flock that the sheep no longer believed that wolves existed.
I have to agree with dkf here. I don't think you understand CI or how it is valuable. You don't need test first or any of that. Your code should always build. CI is a guarantee that the codebase will always build. A guarantee that developers are not committing broken code. From that vantage you can add lots of good stuff: Unit Testing, Style Reviews, Automated Bug Checks, Automated Dependency Updates... But, you have to start with a codebase that compiles and CI does that.
CI doesn't actually keep broken, or worse, flakey code out of your tree, it keeps it buildable, and it keeps new code moving into your TOT. Buildable isn't the same as working/not flakey.
The Mozilla project nearly died under the weight of "buildable, but not working", and it's one of the reasons so many SourceForge projects fail: the elves don't materialize out of the woodwork to fix the bugs for you because they don't have a "mostly working" base from which to make improvements.
It's very possible to get into a state where you commit code that is in fact broken/flakey but buildable, and not have a clear way backwards to working. This happened with the FreeBSD 5.0 schedule slippage for literally years because of stair-steps introduced by resource-based autoscaling of system parameters. Matt Dillon, who initially introduced the problem, and later realized his mistake after the fact, was unable to get the changes reverted, and eventually left and founded DragonflyBSD in partial reaction to the introduced instability. It boiled down to "if you had a machine with the same amount of RAM as the most active developers, things worked, otherwise if you ran up against a resource starvation on a scaled value, like number of open sockets, the OS becomes extremely unstable".
Code has to be tinkerable for people to want to work on it, and if it's currently broken/unstable, it's no longer tinkerable, no matter how many times you successfully recompile it. At that point the barrier to entry curve rises exponentially.
.
Examples are, have always been and probably always will be the weak area of almost all documentation because.
- You _sometimes_ get _an_ example.
- The example is probably trivial.
- The example code is rarely functional (and is probably just a near useless code snippet that you could write based solely on the keyword's definition, above).
The incomprehensible part of this is that the person writing docs could just search the mounds of code (s)he is documenting and pull _plenty_ of examples for each language keyword. And they would be providing better documentation if they _only_ did this (provided the examples were pulled from working code).
In the early days (when dead tree docs were expected), the lack of examples was somewhat justified as it shortened the manual, but for decades it has been feasible to write manuals of virtually any size (i.e. 10 or 100 times larger than they are) and accomplish a heck of a lot more.
I got so sick of manuals that I would just read the Error Codes section (or sometimes manual). Unless _it_ was well done I wouldn't even bother with the main manual, electing to just purchase a manual (after scanning through all the bookstore had on the subject).
I come here for the love
Well said -- Mod Parent Up.
Furthermore, it sometimes happens that non-programmers need to read code for a general understanding of what's going on. For example, a project manager might have to review code after a developer quits.
-kgj
Not all good coders are good writers. (Very few, I'm guessing.)
Not all good writers are good coders. (Very few, I'm guessing.)
It take a whole village ....
-kgj
And it is ABSOLUTELY essential to product uptake and use.
That said, I've been nagging the 50-odd users within my employer of our product (I don't know or care how many sales there are ; many, many more.) to bloody well document their code contributions in the macro language. Out of those 50, and adding the development team (about 10 coders) and our sub-contracting division (another 10 users), to the best of my knowledge I am still the only person who has ever written any documentation for their code.
Which pisses me off. But short of sacking someone, I don't see it changing.
Personally, I think that it's an indication of a lack of pride in their work for people to be ashamed to write documentation and put their names for it.
Birds are not dinosaur descendants;birds are dinosaurs, for all useful meanings of "birds", "are" and "dinosaurs"
"... without causing frigidity or revulsion."
Actual text from box containing sex toy made in South Korea.
When I'm buying a French tickler, I definitely want it to not cause frigidity and revulsion, yes ma'am.
-kgj
Fine. Phone Apple and tell them you will supply the paper (recycled of course) and toner for the manual and you want a copy. I'll await their response with baited breath.
What the hell are you on about? How does that even make any sense? They provide the manual in ebook form and as a PDF. If I told them I'd given them the recycled paper and the toner they'd simply say "surely that would be wasteful to send the paper and toner to us, only for us to send it back to you with words on when you could just print it yourself since you already have the paper and toner".
I'm not sure what response you're expecting that will somehow prove your opinion that not putting printed manuals in the boxes of all their new products is somehow driven exclusively by profit.