Slashdot Mirror
Writing Documentation: Teach, Don't Tell
Programmer Steve Losh has written a lengthy explanation of what separates good documentation from bad, and how to go about planning and writing documentation that will actually help people. His overarching point is that documentation should be used to teach, not to dump excessive amounts of unstructured information onto a user. Losh takes many of the common documentation tropes — "read the source," "look at the tests," "read the docstrings" — and makes analogies with learning everyday skills to show how silly they can be. "This is your driving teacher, Ms. Smith. ... If you have any questions about a part of the car while you’re driving, you can ask her and she’ll tell you all about that piece. Here are the keys, good luck!" He has a similar opinion of API strings: "API documentation is like the user’s manual of a car. When something goes wrong and you need to replace a tire it’s a godsend. But if you’re learning to drive it’s not going to help you because people don’t learn by reading alphabetized lists of disconnected information." Losh's advice for wikis is simple and straightforward: "They are bad and terrible. Do not use them."
Source code is the best documentation.
There's a difference between a tutorial and documentation? Who'd have thunk!
But for those of us who already know the basics of driving, a quick reference is much more useful than a didactically structured text. Documentation isn't supposed to be a tutorial.
Obviously documentation that tells you to read the code is useless, though.
I think one thing the author misses is that sometimes something, even something bad is better than nothing. While a wiki certainly can't replace a professional technical writer devoting a full time job to writing documentation--most of the time your choices are between nothing and something unreliable. In the case of documentation I would rather have unreliable information than absolutely nothing at all. With nothing at all often you will have to scour google for an inkling of a hint. Also wikis on languages like PHP offer up if not corrections at least lots of different examples of usage.
Say what you want but Stack Overflow is an amazing resource and essentially a wiki.
In other news a screwdriver is not the best hammer, it turns out.
From TFA: The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.
No. Experts in their field shouldn't need to be taught how to understand your system; that's part of being an expert ( or indeed, even a professional ). All documentation should be doing is explaining the sticky bits and providing details and/or examples ( whichever is relevant ).
Just my opinion of course. But having stepped in to countless networks/codebases, I can tell you that I just get annoyed when the documentation gets in the way of the information I need to complete my job.
Mod me down with all of your hatred and your journey towards the dark side will be complete!
Programmer Steve Losh has written a lengthy explanation. . .
And we're done.
Provide that in addition to docstrings, and you will make everyone satisfied.
API documentation is like the user’s manual of a car. When something goes wrong and you need to replace a tire it’s a godsend.
Great! That's exactly what API documentation is for.
But if you’re learning to drive it’s not going to help you because people don’t learn by reading alphabetized lists of disconnected information
If you want to learn to program you want to read tutorials not the API documentation...
Most documentation comes in the form of a reference manual for good reason: It is written for advanced users who already know the concepts and need to know the details. If you don't know the concepts, you're the target audience of tutorials. Some people need a tutorial, but all people eventually need a reference manual. It's the more important piece of documentation.
Thanks for pointing out what we've been telling developers for as long as there have been tech writers.
...the author doesn't understand what documentation is supposed to be used for.
Time is an illusion. Lunchtime doubly so. ~ Douglas Adams
Am I the only one who enjoys reading the entire owners manual when you buy a new car?
As an author of three successful dead-tree programming books, I have a few observations.
1) I use the electronic versions myself because of easy search (better than an index) and copy/paste.
2) In book format, it's possible to lead a reader through topics in a sensible order that builds on prior topics.
3) The challenge with electronic/on-line documentation is that there is no expectation that readers will approach the material in any particular order. Readers type a search term into google and up pops a page or two of documentation. How can the author make safe assumptions about the definitions of terms and prior conceptual knowledge the reader will have? Adding links to the definitions of terms and links to chapter oriented conceptual documentation doesn't usually help because readers are impatient, and there is no good place in the middle of the documentation to start.
4) Many readers don't know the terms to type into google and therefore aren't lead to the relevant conceptual documentation even if they would have read it had they known.
I like seeing this alot:
That's it in a thesis statement.
What does 'documentation' or a 'user manual' that **teaches** not dumps random data actually look like???
Complexity is the problem, and it causes blurred lines in areas that in a simpler technical area (with less uncertainty), say auto repair, would not be uncertain.
Computer programs, languages, API's, etc are insanely complex compared to a radio or engine. The parameters and variables are way off the scale in comparison.
Another way to say it is, even on the 'strict' end, in computing there are too many ways to do everything.
A second problem is time. Specifically time in relation to the development cycle.
A manual for a '68 Mustang will always be accurate and usable as long as '68 Mustangs exist.
A complete guide to HTML, CSS, and Dreamweaver...well that can become obsolete in 2 years b/c of changes in the industry. What good is a tome on CSS 2 when CSS 3 becomes standard? It filters down through the whole development stack.
1. Complexity
2. Time
These things cause making a proper 'user manual' that teaches the user like the best user manuals or instructions for other things we've seen.
That's the thing, us tech-minded people know what a good 'user manual' or 'FAQ' or 'help page' looks like when we see it.
The challenge for developers is to integrate educational concepts to mitigate the challenges of the complexity and speed of the industry provide.
We need teachers who can code...we need *women* who can code...
To get that, we need to learn to admit when we *don't know* exactly what we are doing and fess up to the fact that much of computer developmenet these days is done by trial and error!
I don't like it, but we have to accept it to change a whole industry.
Thank you Dave Raggett
Wow.
TFA sez:
But all that is irrelevant because aside from Wikipedia itself and video game wikis, they don’t fucking work. ...wait, what? So, aside from the largest wiki, and indeed, possibly the largest single repository of human knowledge EVER, wikis don't work? Because of your silly driving lesson strawman argument, too pedantic to repost here?
Yeah.... I really don't want to read *your* technical documentation now.
The article misses something critial - the use of common language.
The biggests example of this is HIS use of "user". A "user" for all my time in this business is the person sitting in front of the computer using the software to preform a business funtion... not programming a business function.
This leads to second issue a developer is person that uses an embedded function written by another developer - generally with a higher skill or at least akill peaked before the new developerl. That developer is trying to come up to speed about cause and effect of using a given piece of code and trusting the original developer actual did his job right.
How can you trust a person that says what documentation is to be, that cannot teach it following his own rules? The first rule of any teaching is placing terms that you are going to be using, to teach the others what you mean. You see this legal documents to prevent confussion of common terms being used in a more defined or limited manor.
In my opinion, Stack Overflow is most often the blind leading the blind. There will be 20 wrong answers, 10 answers to the wrong question, 2 suboptimal solutions, and if you are in luck there will be 1 good solution. Now, tell me which is which. It seems to me that the good answer is almost always buried under crap.
Stack overflow questions are often badly stated and difficult to find with more correct search terms. If you don't even know the search terms, the site is useless.
There have been a few times when stack overflow saved me a lot of time. There have been many times when stack overflow has been a pointless time sink.
to Windows users. You can guess how far that's gotten me!
But . . . er, uh . . . without a wiki, just how do I get a bunch of tech-weenies like myself to create documentation if I can't afford the services of a professional technical writer? M$-Sharepoint? Oh, wait - I know: we can go back to the "good old days" when policies and procedures were part of an organization's oral history.
At the end of the day, Mr. Losh may be prepared to speak to the documentation situation where he's at and where he's been, but he still doesn't know diddly about where I'm at and what I'm dealing with. I recommend readers assign the appropriate credence to Mr. Losh's assertions.
I agree with your superficial point...who would have thunk it indeed
However, I think it is still a distinction without a difference, one that only causes more confusion.
You and I know what 'documentation' in the computing sense means, but it's not a logical concept for a non-techie.
'documentation' in computing can be as simple as the coder showing his/her work and making a formal log of changes and bug reports/fixes
however, and here is where the problem happens...what constitutes 'sufficient documentation' for a coder is *not* sufficient for a user!
the problem is, that to bridge the gap, most programmers (who are not at all schooled in education theory & by nature tend anti-social) must create some sort of 'document' beyond the 'documentation' for the end user
sometimes this takes the form a 'tutorial'
a 'tutorial' is not full instructions...it is a real-time step-by step *demonstration* which may have supplimentary material that is actually instructions
ex: I can make a video with the steps to start a car, put it in gear and how the brake and throttle work...a person, with *nothing* else but that video and factory plans of the car *could* learn to use it...but calling a basic video and factory plans 'instrucitons' is insulting!
'documentation' can be helpful
'tutorials' can be helpful
'help' menus can be helpful
even so, its not a full user manual that an end user in other industries would expect
the computing industry has decades of work in this area I fear...so many have gotten used to doing it a bad way
Thank you Dave Raggett
peaked before the new developerl.
Freudian slip much?
Have gnu, will travel.
I run Windows!
Since when did the car owner's manual teach the owner how to drive?
I work for an airline. We train pilots on our aircraft and our procedures. We certainly do not teach them how to fly.
Document everything that you would have liked to have seen / needed to know if you'd suddenly been placed on the project at short notice.
Document your code for other developers : a single sentence is often enough to explain what a block of code does.
Don't make the readers of your code run every line in their heads - if the code works then they can read the documentation quicker.
Documentation must be maintained as dilligently as the code (nothing worse than wrong / obsolete documentation).
If you had to really think about it, document it.
Don't add unnecessary documentation (i++ // incerment i by 1)
If you believe that "all code is self documenting", go and work somewhere else, because at 3.a.m in the morning the developers trying to get your shitty code working will probably want to do you some harm.
developers, take notice because these words ring true! while there may be some quibbles among people about details in this article, there are two things that have are universal truths.
auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation.
...
[crowd written] Wikis are an abomination. They are the worst form of “documentation”.
you have no idea how many times i've heard developers tell me to read the documentation only to find out it's just Doxygen generated with very sparse non-code text. it's a nightmare. "crowd" written wikis are terrible for code documentation, no question about it. however, privately written and maintained wikis can be a good editing tool for documentation.
if you want a good example of good documentation, check out the Qt documentation, it's has all the great things discussed, it's on the web, it's in a independent program and it has plugins that integrate it into IDEs.
*drops mic*
Anons need not reply. Questions end with a question mark.
For an API there's probably 90% that is almost never used in day to day operations. It's either there as infrastructure supporting the framework or is there for use in rare corner cases. Thus an example goes a long way in showing typical usage of how these things fit together. Same goes for all those man pages with long lists of arguments, when in reality almost everyone always runs that particular command with the arguments -Duv for most practical scenarios. If done right, the technical specs+practical examples, you should be able to jump to either one without the other being "in the way". You do know how to use your scroll wheel right?
Without practical usage, it's kinda like getting an assemble-yourself -plywood-furniture with all the pieces and screws, but without the instructions that show you how to put it together. Yes, you could argue that someone could manage to get it together without those instructions, but it will be much more difficult, and they will likely do things wrong. Just as when using APIs sometimes, people find ways to get it done, but without knowledge of some of the nuances of the framework they might be doing something wrong. This is often the case with someone rolling their own encryption, where someone gets something working but it is insecure because they missed one little nuance. If you can read the RFC's and manage to get something together, that alone is impressive, but maybe they didn't know they should also read the entire article on generating key materials properly and thus the whole thing is unapparently insecure.
A programmer using a library is a user of that library. The person programming a piece of software is not the end-user of the software being written, but she is still a user.
Life feeds on life ...
feeds on life
feeds on life
end user is on top of the food chain, is all.
We wrote two documents for every program (of any significant length), a "user guide" and a "reference manual". That's in addition to the man page and the "usage" blurb if it was invoked with nonsensical arguments.
They fulfill two very different needs.
(now get off my lawn)
There's also something to be said for "sell, don't tell". I seem to recall that the Commodore 64 Programmer's Reference Manual was written as if they were enthusiastically pitching the product. For some reason, it was much easier to retain the information when the author gushed about it.
For all intensive purposes, "whom" is no longer a word. That begs the question, "who cares"?
I think the author's tirade against wikis is that many people use a wiki as a magical tool that allows them to forego writing documentation in the hopes it will suddenly appear, written by users that want to write documentation. This obviously isn't what typically happens.
However, I think wikis can be (and often are) a great format for documentation. The author(s) of the software should still be the primary and/or only contributors, but even so good wiki software serves to lower the barrier to writing documentation: creating/editing as simple as clicking edit, and you instantly see the results. You can link between pages, reducing duplication. Some software forces a hierarchy of pages, leading you to create things in a logical, structured way (of course, you can lead a horse to water...).
The key to this of course is that the person/people writing the software must write the bulk of the documentation (eg, like you would without the wiki as well). Don't allow random edits, or at least subject edits to a review process.If your project is big and successful, just as it lowers the barrier for you to write docs it may encourage others to contribute -- but don't rely on this.
Think of the wiki more like a publishing platform or format; not like a way to absolve yourself of the responsibility to write documentation.
Speak before you think
To be honest, when I say that "not all wikis are Wikipedia", I'm still being a bit unfair to Wikipedia. Even that project - which puts, for all practical purposes, zero dollars into content creation - still has recognized that at least some regulation is a good thing, and that even if you give everyone read access, you don't have to give everyone write access. Further, with their Pending Changes process, not all changes to a page go live immediately--for certain pages a reviewer has to approve edits before they appear on the outward-facing Wikipedia article.
A private company or organization can appoint gatekeepers to control who can edit what, and who can approve changes. Moreover, they can pay people to edit documentation, and can impose requirements and standards across the project. Wiki software can provide a lot of 'back-end' support for creating complex, multi-page, potentially multi-media documents, using markup that is relatively straightforward to learn. It can provide clear, complete records of who changed what, when--and who is responsible for breaking stuff.
Sure, waiting for people to randomly show up and write documentation, and then accepting everything they give you without any validation or quality control is a recipe for failure. But that's not the only way to use a wiki. Linus doesn't let just anyone check stuff into the kernel.
~Idarubicin
I love reading great documentation. When I have a question and the documentations explains the answer almost as if the author has magically anticipated my problem, I get a warm, fuzzy feeling inside.
I too love reading great documentation. Documentation that does not change the point of view twice. And then back again.
... documentations explains ... I’d like to say thanks to ... for proofreading this.
Documentation that was PROOFREAD by GOOD PROOFREADERS !!!
up-to-date-ness
I've been writing technical documents since the early 1970s.
You can't expect one piece of documentation to serve everyone ... it's like buying a "vehicle" and trying to use it to race, haul hogs, and climb Pikes Peak.
A - Ordinary users don't give a shit how the stuff works, they want it to do something for them ... tell them how to make whatever it is work as a tool for them. Run through the common use cases, screen by screen, showing them how to make the widget-smasher do it's thing.
Start with things the way they should work, then give them some basic troubleshooting, maintenance, etc.
B - Administrative users: They need all of "A", and how to handle the other users. Add, remove and monitor users.
Start with things the way they should work, then give them some basic troubleshooting, maintenance, etc. for the added functions.
C- Service techs, sysadmins, and those who will touch the sacred code: All of A and B (be reference to the appropriat4e manual or section thereof) and then feel free to pile on the technocrapobabble.
Each detailed explanation should start with a very brief "statement of purpose" ... when will this command be needed, or what does the bit of machine do. Why would you use it?
Then explain how to use it, and the expected results if you used it right, the expected results if you screwed up, and how to recover from an error.
======== ... chronologically, what touches it and what is supposed to happen?
You need to explain for each level of user what happens to a transaction, or data, or a part being manufactured, as it passes through the process or the proigram
What will you see if there is a failure?
How do you recover from the failure?
It's not difficult, you just have to make sure that each level of user can get their task done efficiently.
That's how I got my entree into writing about Linux. Programmers are very smart, but not very eloquent and they are also very poor teachers.
There are any number of rules and guidelines for writing documentation, most of which are ignored since documentation is often the red-headed stepchild of the project.
Documentation should tell a story clearly and help the reader understand the 'why' and 'how' as well as the 'what'.
"I believe in Karma. That means I can do bad things to people all day long and I assume they deserve it." : Dogbert
Yeah, this is one of the big annoyances with *nix man(1) pages.
Between "Name" and "Synopsis", they're all missing the "Typical usage examples" section. I shudder to think how much time has been wasted through this poor design choice.
I'm an end user, although one that likes mucking about in Linux, flashing a new OS on to my phone, and generally getting into the guts of whatever tech I'm using.
Maybe it's just because I'm old enough to remember trying to make early Linux distros work relying on Man pages, but "documentation" tends to be the last place that I look for answers. I still shudder to recall that understanding Man Page A required understanding Man page B required understanding Man page C..... I just wanted my modem to work!
The problem is that so much documentation is just too much for day to day needs. I don't want to understand the technical underpinnings of Android or Debian packages I just want to know how to make a problem go away. Simple questions require simple answers.
Instead I rely heavily on Google + Forums for probably 98% of my needs. I really need to have a very, very obscure problem to find that no-one has figured it out yet. (At which point I dutifully file a bug report)
Finally, am I alone in finding that whatever technical support docs are available on corporate sites are useless?
Three Squirrels
I produce a lot of documentation along with my coding, and the one thing that makes it palatable (even to me, re-reading it) are illustrations.
I'm not talking about UML class or activity diagrams, although those things are great where appropriate. It could be anything relevant to getting your point across, like a fragment of a database table showing sample data so people can visualize how a group of tables will work together. Screen grabs with arrows and circles.
My rule of thumb: if I ever find myself drawing a picture on a whiteboard as I'm explaining my module to someone, I immediately stop and take a picture of the diagram I just drew, and ASAP afterwards I turn that picture into an illustration in the user docs. Then next time I can just whip out the docs and point to the illustration.
Koans and fables for the software engineer
Not documenting is a more or less conscious technique developers and projects use to increase their market value. In those projects where the business model is consulting , you better believe that unless it's a public API , it's got zero documentation.
I know this is true. If software developers wanted to , they could write a nice book about how their source code works (as opposed to how their program works or how to write a plugin for their program).
They don't. This is not merely a case of being rushed for time or whatever. They don't want anyone else to understand it really. You control what only you understand- every developer knows this intuitively. Going to great pains to write a book-style learning aid to your actual code so that *just anyone* could take your place.. well... do I really need to finish that sentence?
Devs (don't) do it to so they can get some job security. Companies (don't ) do it to get consulting gigs. No one will admit that this is what's going on, but it is. I can hear the rebuttals already.. I can see the down-modding about to happen... go ahead.. flamebait me down. .. knock yourself out.
The closet analogy I can think of is magicians guarding their secrets. That worked very well for a long long time. The incentive was the same. If you give this away, if you make it understandable, you're going to be out of work. Slightly different dynamic, but you get the idea.
This is one of the product spaces we want to move into, but as you might imagine we have come to the conclusion that we have to move carefully, and even obliquely.
This is not exclusive to software engineering either. I know for a fact - which means i have multiple, full confessions, that mathematics teachers are far less clear than they could be wit their students. Some have said they do it to winnow out the weak. Others have admitted they do it to classes to students they don't like. They know it makes a huge difference, how you explain something- and that no one can accuse them of anything. That's basically a kind of power or force you can wield against and for people who please you or displease you.
Just sharing what I know.
The same way your managers answered the question "just how do I get a bunch of suits to create a business if I can't afford the services of professional tech-weenies who can write actual code? Excel Macros?"
When you have a business need for a professional tech writer: hire one. (Even if you do it on contract. Chances are your developers will learn a fair bit too, because they have to explain things to the tech writer well enough for the tech writer to get started. You'll wind up with a better product, and you'll probably find some bugs you had no idea existed.)
Losh's advice for wikis is simple and straightforward: "They are bad and terrible. Do not use them."
With that quote right there he's lost all credibility.
A well maintained wiki with proofing, editors, publishers that has management on-board is about the best way to document anything. He seems to be referring to the often found, random wiki the local coders threw up for lack of anything better... yes, those are bad. But a well maintained one, that actually has official practices and peer review... Where you get a project to write or update something, and then someone else gets a project to edit it, and then the entire team peer reviews it before it goes to a "publisher" who then publishes it to the wiki officially is great.
In my job, published edits to our wiki documentation are something you can use for promotion, raises and even to get new positions. The "stars" at my company are the ones making the most published edits. And note, I say "published" edits. You can make all the edits you want but if they fail peer review you just wasted several hours so you'd better make sure they are worth-while and done well.
It is not the responsibility of the student to fix a broken lesson plan. For fuck’s sake, the entire point of having a teacher is that they know what the students need to learn and the students don’t!
This. I've lost count of the number of times as a medical student when I showed up in a pompous consultant's teaching session, (arranged with great difficulty, no less), and the first sentence was "So, what would you like me to teach you today?".
If I knew I'd have gone and read about it myself rather than waste time here with you, thank you very much you arrogant prick!
manor? Please define your terms upfront.
Nobody here is concerned with discussions held on small English estates.
1) Nobody writes it.
2) Nobody reads it.
If documentation were free, then implementing all the suggestions would not be an issue. In the real world, however, time and resources are always constrained, so documentation is a balancing act between utility and achievability. Moreover, for a company whose revenue depends on service contracts, it might not be in the company's best interests to eliminate client confusion with better documentation. I vaguely recall some story about Bill Gates who objected to having (I think) docx structured in a way that would allow a person to modify it by hand because it would loosen Word's grip. In other words, complexity and opacity can align with corporate interests.
There is another problem with spending a lot of resources to produce great documentation, however, and that is that as the software being documented evolves, the original documentation becomes less and less valuable. Although the original documentation might win awards for clarity and usefulness, it might be close to useless in only a few years, and nothing but another herculean effort will suffice to update it. This might be worthwhile where millions of customers are involved, but for a user base of only thousands or tens of thousands, great documentation that is also current can eat up profits.
job.
I was told how much my documentation sucks because the information they needed to operate the device wasn't in the manual. I challenged the person complaining to tell me something that was left out. I turned to the page in the manual and pointed to every answer that was left out.
Eventually the person complaining finally said "It's a bad manual because you have to read it to use it."
That's exactly the answer I was looking for.
My current place of employment does not want educational manuals. They want step by step instructions. I haven't written another manual for these people since. At my previous places of employment they raved about how good my educational documentation was. As a matter of fact the support manuals I wrote of an ISP in early 2000 that included modem and email troubleshooting leaked to other ISP's and outsourced call centers who began to implement the pirated copies into their own resources. I finally put a documentation GPL on it and released it all to the public (I've had people criticize me for not using Creative Commons, but this was a couple of years before that hit).
The lesson I learned - technicians want to learn. Monkeys only want "monkey push button".
The preceding post was not a Slashvertisement.
Always find it a bit odd when people complain about documentation, or place emphasis on it. My first prioroty is, "it works".
On the other hand, it is hardly clear in most cases, who the audience of the comments are. Do they know much, do they know little? If they know little, there needs to be a lot of documentation. Who is to say?
So when I hear about people, who mention bad documentation, or who complain about some documentation, it strikes me a bit odd.
Stephan
http://stephan.sugarmotor.org
I heard the shrieks of thousands of terrified brothers and sisters. It was the cries of the carrots... Tomorrow is harvest day, and to them it is the Holocaust.
Documentation is for people, not programmers.
Many here seem to think that programmers write software for other programmers. Some do, but look at the 'Dummies' books- they are for people. People who have to do accounting, who have to write with Word, who want to know how to assemble an Ikea coffee table.
As an Apple ][ user and then a Mac user, I've never needed a manual to run ordinary programs. Autodesk CAD software and Mathematica require some instruction but most stuff just happens as you expect it to. If a Mac program requires documentation, it's probably defective as programmed.
OTOH, dBase was written for DOS programmers. It was complicated enough to discourage ordinary users and provide a market for middleman scammers who would create simple databases for small business persons and make them dependent upon them forever after. Those end users using the Apple or Mac in the early days could easily create their own hierarchical or relational databases without a 'consultant' because the software was user friendly.
I am a senior member of the Society for Technical Communication (STC) and it is my business to communicate obscure information from programmers, scientists, engineers and other snobs so that regular people can understand it. If that information was properly organized by people with common sense, I would be out of work.
...omphaloskepsis often...
API documentation and especially external API (and actually Application PI) should contain enough information (that is documentation) so that a person can use it successfully and correctly in most situations. It should point out troublesome situations.
If you don't, then you are saying it doesn't matter.
Or maybe you think people should spend a lot of their time finding external information, killing trees producing multi-inch thick books, reading them and being out the cash, because it does matter. (But not to you specifically.) Or, maybe you don't think a typical programmer has to stare at other peoples code enough.
So you made an api, but you cant produce concise, useful information. Elegant and understandable is for chumps.
Thanks a lot, expert.
Once you are at the component level or have a high fan-in, what you have should make sense. Then all you can say is that it wasn't worth your time. It should be (very) obvious, take very little time to verify any normal question, or be an exception rather than the rule.
Well, the authors says: "I also love writing documentation.". So, there you have it. If you like doing that, then please do the kind of docs that you'd like to see from others. Me, not so much a fan of writing lengthy blabber, and in documentations I prefer conciseness, easy searchability (i.e. use the proper terms and wording), and quick & to the point examples. Put the rest in a book that I'll buy, put in on my shelf, and never use.
Most docs are written by people who didn't do it by choice, and it shows, but if they were put together by someone who knew their stuff, then they are still usable to the generally knowledgeable in the area. If you want to write for rookies, go ahead, but most of those texts cause me exceptional headaches.
I am putting myself to the fullest possible use, which is all I can think that any conscious entity can ever hope to do.
define 'non-techies' my friend...
it's a sliding scale...my grandma is a 'non-techie'...so is my cousin, her great-grand daughter...both non-techies...one uses the internet, facebook app, instagram app, edits photos, and maintains a blog...
both are 'non-techies'
in that same way, take say a Cisco certified Network Admin (I used to be one)...they are 'a techie'!!
however, techie though they may be, a CCNA could be gainfully employed for years without ever being anything other than an 'end user' of an API, if they ever use one at all...
so, in this manner, an IT professional with a decade of experience could be a **new users** of an API...
**IN THAT CONTEXT** they need and are logical to expect some 'document' that functions as a 'user manual' of some sort
it's a sliding scale...'techie'....learn this lesson now
Thank you Dave Raggett
You're on linux, aren't you? There, all the manpages used to say "go read our proprietary* texinfo crap using the proprietary* reader**, because our shit doesn't stink", and even though projects like debian do try and come up with workable manpages, they're only half succeeding. You can't simply wipe out institutional stupidity in a day.
Manpages, when well-written and curated, are fine as the handy-dandy on-line reference manual. They ought to have everything the professional needs getting work done, where "professional" is someone who already knows the overview and what tool would be well-suited for the job.
If you don't know that, you need a different kind of documentation. And so you need a system that understands that. BSD didn't come with just manpages, it also came with several handbooks full of articles on various systems. FreeBSD, next to its high quality manpage collection, still maintains an ever-growing handbook next to a collection of articles and a FAQ for all sorts of gotchas, plus these days a wiki to collate information for eventual inclusion into articles or handbook chapters. Next to all the ways you can ask people more knowledgeable than you, so common in the open source community.
It isn't perfect, of course. You really need a curator (or a team of those) to keep the quality up (personally I feel FreeBSD is a bit slipping here, though they're still miles ahead of others I could mention), and that's boring work. And it's a large project with lots of words to care for.
Same problem with wikis: They're great for gathering all sorts of fragmentary information from multiple sources, but they need someone to copyedit, to curate the content. Starting with spelling and grammar, and going from there. In the end you still need technical writers. You occasionally need a fresh intern to try if the results are any good, just like the "hallway testing" that helped apple create such well-regulated interfaces to their software. But that doesn't change that wikis are great as buckets to catch information that would otherwise up and vanish. It's just that merely catching the information isn't enough.
Likewise, merely providing good-quality manpages isn't enough. It is, however, a good start and still much better than what you usually see provided.
* Nobody else uses it. That makes it de facto proprietary, no matter how religiously "open".
** "If we can't find an info page, we'll present a manpage in our proprietary reader because that's obviously superior to your preference that you set in PAGER. If you're really lucky, the manpage will still tell you in snooty tones to go read the (apparently non-existing) info pages instead. Verily, our excrement does not ever smell, sir!"
Seems like a nerve has been hit.
If documentation were free, then implementing all the suggestions would not be an issue. In the real world, however, time and resources are always constrained, so documentation is a balancing act between utility and achievability.
That's why the author advised you to take a typing course if you haven't already, because then writing your documentation takes about as long as thinking what you should write.
As a professional technical writer, published author, and university instructor, I can tell everyone here that developers should never be permitted to write their own documentation. No amount of blogging and helpful hints is going to turn a programmer into a teacher, unless she already is both. Even then, there is a huge potential for disaster. The person who creates something should never, ever be the person who documents it. The creator is just too close to the product. Zen mind is beginner's mind. This is why UX focus groups consist of naive users, not experts. And the developers are the most expert of all possible experts. Sadly, software companies, at least in the digital content creation sector, seem to have fired all of the technical writers as a cost-cutting measure. The quality of documentation from many companies (I'm looking at you, Adobe) has plummeted. Nowadays it's expected that any issues with the docs will be resolved by the users themselves via discussion forums. It's a travesty, I tell you.
When I'm trying to learn something new, I don't like reading documentation, I prefer reading a textbook written just for me. So please, when you're writing documentation at the work place, think about me! On the off chance that I could become your colleague, and furthermore, in the event that I should have to maintain some of your software, I will be very pleased to read a texbook you wrote for me. I may even kiss you (if you're a girl), and you will definitely get a gold star drawn in crayon on your scrapbook (regardless). That's how committed I am to having an excellent personal learning experience.
So slashdotters, now you know! Make it happen!
Though there seems to be a lot of good advice in this article, the author rants misguidedly against several things. As someone has pointed out already, he seems to be addressing the writing of tutorials, but labeling that "documentation for programming languages and libraries." While good tutorials are often sorely lacking, that is only one type of documentation for programming languages and libraries. API documentation is extremely important as well and literate programming and docstrings fit in a similar category. The author's rant against wikis is particularly funny, especially since he acknowledges that there are quite useful ones. Of course there are many wikis full of poor quality information, just as there are many essays and blog posts of poor quality. Blaming a wiki for the poor quality of its contents makes no more sense than blaming one's editor for the poor quality of one's code.
I have worked on several large product from MAJOR vendors that provided over 800+ pages to document a simple API that could have been done efficiently in less than 40 pages. Because of this, the project costs drastically increased due to the complexities of implementation. I ended up reducing the documentation to a 40 page document that included "cut and paste" examples of which, if had been provided earlier, would have increased productivity time saving overall costs of the project.
Sometimes too much documentation is a bad thing.
The rule:
1 page (or less) per API call. Anything more and you're a fucking moron and should be fired for stupidity.
He didn't say "experts need to be taught", he said, "teach someone to become an expert." Big difference.
"We receive as friendly that which agrees with, we resist with dislike that which opposes us" - Faraday
Whether on StackOverflow, microsoft.com, or ANY OTHER WEBSITE OR ELECTRONIC DOCUMENTATION, please for the sanity of everyone involved clearly state up front:
1. what date it is now, when you write it
2. what version of the immediate software (API, etc.) and supporting software (language, runtime and OS at minimum!)
These will help the rest of humanity to understand the context in which you're proposing your documentation, question, or solution. If it is on a wiki, then create a new page for the new version and leave the previous one(s) up!
Thanks, people!
Great solution, I agree with the article. All software should point documentation to learning how to program (in the language the application uses) books for the user that are known for "teaching the user". Then the user is no longer a user, but a programmer and can use the sourcecode for documentation.
Genius.
Change is certain; progress is not obligatory.
FLOSS projects need new developers from time to time to remain viable. The issues for user documentation apply to developer documentation, too. New developers need to be taught the structure and conventions of a project so that they can find their way into it.
-- hendrik
... having spent decades fixing and enhancing code written by others, frequently no longer there.
"Teach" *may* be appropriate, if you're writing architectural documents, including the logic, but for system documenation for users, you don't teach: you write it so they can read it, and it MUST BE CORRECT and CURRENT, not some crap you threw together and fuggecaboutit.
If you want the right way to do it, I can offer one that was demonstrated to work when I developed it. My article on it, "Egoless Documentation", was published in the now-sadly-defunct SysAdmin magazine in '06: http://24.5-cent.us/egoless_docu.html
mark
Yes. Do that.
In education psychology and education design grouping information in that manner is standard practice. A teacher might identify and concentrate instruction time most heavily in the most important areas of a task analysis.
FYI, in education today, every lesson plan starts with a 'task analysis'....ed. majors are taught to analyze "what should the student *know* and *be able to do* after the lesson is finished"
Its two factors 'know'...as in a test of knowledge of data....'be able to do'...the all important second step of applying the data to solve a problem
Sounds alot like a user task analysis, no?
Another reason why I like the 'teach don't tell' mantra...
Time for some coders and engineers to audit an educational psychology class!
Thank you Dave Raggett
Yes, I am using Linux. Totally agree about 'info' --whatever its technical merits, it embodies the worst elements of NIHism.
I used FreeBSD 2.2.21 for a while (about 2000 to 2001-ish) and the man pages were better definitely much better. And the handbook was good. I also bought 'Grog' Lehey's "Complete FreeBSD, and that was useful too. FreeBSD did have a good documentation team ... once upon a time. (But, dammit, I wanted my USB Frobulator to work. Now, today, this minute! Or something like that, anyway; I forget. So I switched to Linux.)
Sigh. No need to get off my lawn; it is sere and withered. Enjoy the broken bottles, rusty cans, and poisonous spiders in the long grass, you young punks.
Of course that is a rhetorical question and it is an answer to the flanebait that started the discussion which said to read the source, provided you have it. But if source code were so readable, it seldom is, then source would be the only document you need. People have pointed out that coding practice often inverts the logic of action, especially in OOD, The other truth is that most developers are poor writers and even though they are capable designers they can't explain the design, especially to a novice. This is a forest for the trees problem and relates to the role of educational techniques in spreading knowledge. The discipline it takes to develop and test and debug an object hierarchy in a modern language is often the reverse of the steps it takes for a novice to understand what it does, which is why reading the source is often the worst way to learn what an application does.
And still most people who develop cannot write. The proof of this is to read what documentation they do write. It is highly uneven in quality. While a tutorial that is written to advocate for a piece of code, a programming language, a library, might be quite readable and interesting, such as the kind of article that appears in a newsstand computer magazine, or on the main web site for a product. It doesn't take much delving into using the product or code to reach an inflection point where the character of what is documented changes abruptly into a specfication document and in which the writer has left out, or worse, glossed over, some pesky detail, whose inattenion to causes your project using the tool to fail and to not be easily and timely fixed. If developers want to know why what they do doesn't get used, they need look only at this problem.
On the other hand poor or non-existent document may serve a purpose. It may guarentee the elites an existence and provide a barrier to entry by less than elites, average or bad programmers and users who the elites say shouldn't be messing around in the innareds. The risk of that is slow adoption of the product, which can hurt developer security if the product has been over-hyped for its ease of use, when its use is hindered by poor documentation.
I consider myself a bad programmer, but I have experimented around with many programming languages, most recently Python, and have been looking for tasks to ignite a passion to get something done and to relearn the right way to develop applications. I have an avid interest in music and serious music composition, I can remember large works easily and know a great deal about the literature, so I was quite interested when a composition program written in Python came may way. I won't tell you the name of the software, but it was the usual approach, a collection of objects and methods to do various tasks associated with scales and pitches. There was some good tutorial and example code, but the use of it quickly became arduous, because the tutorials and examples emphasized the easy things to do and the other things you might want to do were either ignored or the jump off into the object hierarchy was so deep that you couldn't wade through the complexity. I wanted to go from the relatively easy processing of musical parts, horizontally, into the vertical aspect of chords, and in particular to be able to generate reasonable piano reductions of open scores based on where the pitches crossed from the left hand to the right with reasonable intervals. Not only had this not been tackled by the software design, but because of the ease with which Python handles lists, the emphasis was roo much on processing parts and not enough on harmony.