RTFM? How To Write a Manual Worth Reading 244
An anonymous reader writes with a link to Rich Bowen's insightful, detail laden piece at Opensource.com about improving documentation: Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person. What's the best example you know of for open-source documentation? How about the worst?
One thing to keep in mind... (Score:4, Insightful)
Make it conversational as well as informative. You don't have to write a novel or make it into a drama play, but at least do something to help illustrate a bit more than some short and often mis-communicated list of what the options do. In technical speak? No problem: less man page, more info page (speaking of which, an actual info page would be a nice thing to have for a few of the projects out there, eh?)
Re:One thing to keep in mind... (Score:5, Insightful)
Make it conversational as well as informative.
On a related note, often with OSS there are more than two parties in the conversation.
If I'm configuring some sort of local mail store, I don't just need to know how to set up Dovecot. I need to know how to set up Dovecot, Postfix, Roundcube, and so on, and I need to know how to set them up together.
If I'm configuring some sort of Linux server, I don't just need to know how to set up RAID, I need to know how to do it with logical volumes for future-proofing, and I need to install a bootloader that understands. And then I need status monitoring, and procedures for recovering after failure, adding more capacity, and so on.
Frequently with OSS, particularly sysadmin-type stuff, I find there is more detail than you would likely ever need about any one part of the system, but the real problem is figuring out how to connect it all up in practice.
Re: (Score:2)
Post to undo a misclicked mod. :(
Re: (Score:2)
info's info page looks like a converted man page on my system! wow.
Most missing in its documentation is "NOTES : This program is unusable, use pinfo instead."
Man pages themselves could see some color.
Re:One thing to keep in mind... (Score:5, Insightful)
Strongly disagree, documentation should get straight to the point.
Detailed reference documentation, yes.
But more often than not, the problem with OSS seems to be that no-one wrote the introduction/overview/big picture stuff, and the developers instead expected that users would just magically discover that kind of understanding from 1,943 man pages with cryptic names and no context or navigation to show them where to start.
Re: (Score:2, Insightful)
That's a different thing from a conversational tone.
Yes, there should be an overview and lots of examples but it still should be written concisely.
Re: (Score:3)
Not really. We can debate the meaning of tone, but 6 sentences that meet your criteria stop being conversational if they are out of order, or missing.
Re:One thing to keep in mind... (Score:4, Informative)
Nobody likes dry reading. but they got soppy dripping wet.
Re: One thing to keep in mind... (Score:2)
Re: (Score:3)
Re:One thing to keep in mind... (Score:5, Informative)
I totally agree.
I've seen countless man pages that don't even bother to say what the command *does*, let alone *why* you would want to do that. They assume it is all self evident (I'm guessing the author's logic was: "or else why would you be reading about the flags if you didn't already know you needed it and for what?").
Also, sometimes explanations are vague--being precise about the behavior (especially if it is altering data) is important.
Re:One thing to keep in mind... (Score:4, Insightful)
This is not just a problem you see in command line or open source software. You find it in the documentation of many niche applications and it's invariably because it was written by one of the developers. Someone who has spent months working on the software, so it doesn't occur to them how someone completely unfamiliar with the software might approach it, or what they might want to know. So you get online documentation that dives right into technical details, scarcely touching on an overview of what it actually does.
And this happens even with software where the developer wants you to buy it. Just how many sales they get when the potential customer has to first puzzle out what it is, I don't know.
Re: (Score:2)
This times a million.
Even in commercial software, for anything detailed, it is often better to just look a code. I don't trust the documentation to be up to date for anything detailed anyways. Enums, magic strings, detailed algorithm behavior... let me see the code (auto docs work good here as well)
But the one thing often lacking even in commercial projects is the big picture stuff. Showing all system, what is being called, big picture structure, where the important starting files are...
Re: (Score:2)
...expected that users would just magically discover that kind of understanding from 1,943 man pages with cryptic names and no context or navigation to show them where to start.
Sometimes I wonder if this is deliberate, as they had to spend many a grueling all-nighters to figure out all this stuff so newbies will have to do the same. "Of course it's hard. But that's what it takes if you want to be part of the Few, the Proud," (uh that phrase might be copyrighted by a govt agency).
Re: (Score:2)
Getting Started: Covers basic setup and configuration. It gets the user up and running step-by-step with the defaults complete with screen sho
Re: (Score:2)
Or even more charming is when the instructions are very brief and just tell the 'new' differences with the previous version. So then the changelog becomes part of the help files...?
Lousy help files have cause me to uninstall more than a few open-source programs, and I bet
Re: (Score:2)
I agree here. Especially when encountering new stuff or concepts, most documentation is unhelpful. Ie, learning how to use PGP using only their reference manuals is daunting; or a newcomer learning how to use Berkeley style sockets using only man pages leads to many mistakes.
Re: (Score:2)
Absolutely.
I can't count the number of times I've come across an open source project online, and couldn't figure out what it was
When I worked at SourceForge, this was a major thing I worked on. I called it the "Yeah, but what does it *DO*" campaign, and I'd try to get projects to explain what their project was actually for, rather than saying that it was "an effort to build a fast, efficient, best of breed tool XYPDQ object-hierarchical framework" or whatever.
Turns out that a lot of people find this kind of thinking revolutionary. It's honestly eye-opening when you say some people might not know what their whizbang is used for.
Re: (Score:2)
As I mention in the article (you did read it, right?) is that there are different voices required for different types of documentation. There's a place for both the "straight to the point" (reference docs) and "conversational" (howtos, more learning-oriented exposition) voices, depending on who you're talking to, and how much they already know.
OSS needs technical writers more than coders (Score:5, Insightful)
Coders they got. Projects whose "documentation" consists of anything more than a technical list of bugfixes they don't.
OSS needs to realize that well-written documentation is just as important as well-written code.
Re: (Score:2)
Oh yeah, and a message board or empty wiki doesn't count as "documentation."
Re: (Score:3)
Re:OSS needs technical writers more than coders (Score:4, Informative)
TLDP had a lot of problems and they weren't all internal to TLDP. I think the biggest one was that we were trying to balance between documentation style and authoring while trying to make it easy for people with little documentation skills to write. It isn't as easy as writing a word doc and uploading it - we were trying to make it so you could read documentation on any format: PalmOS, PDF, Word, printed, HTML. Docbook and linuxdoc made that process easy, but it was a markup language and the best way to write it was as by doing the markup yourself (think writing HTML by hand) and there was a lot of infighting about going back to linuxdoc. As the documents became more complex it was difficult to do technical reviews since a lot of the people were more documentors than technical. As Linux grew and advanced, nobody was available to update old documentation because they were working on new ones, so much of the existing content became stale.
and the programmers should not write it (Score:2)
You can be a programmer and write documentation, but if you want good documentation, the person writing it shouldn't be the same person who wrote the code.
The problem is that you're already too far in -- you understand the design issues, the quirks, etc. You need someone with a fresh view to write the documentation who doesn't come in with a lot of implicit knowledge of the inner workings of the software.
My boss has a policy that it's the newest or youngest person on the project's job to write the document
Re:OSS needs technical writers more than coders (Score:5, Insightful)
"It isn't hard to code well, it just takes time" - said no writer, ever.
Re: (Score:2)
Exactly. Writing code and writing technical documentation are different skills.
Often different people will have each responsibility, and then identifying and accurately communicating the relevant information between them is a third essential skill.
Re: (Score:2)
The hard part is being able to design really great software or meaningful written works. I'm more than capable of learning the writing skills necessary to produce a novel, but honestly I don't think I could actually write one that anyone wo
Re: (Score:2)
Incorrect, and arrogant. It IS hard to write well, it is a skill, it can be learned, and not many in the tech community have it.
"It isn't hard to code well, it just takes time" - said no writer, ever.
Anything is easy if you've never done it.
Re:OSS needs technical writers more than coders (Score:5, Insightful)
I guess what I'm trying to say is, don't skip review and just post the documentation. Give the documentation and software to someone not familiar with it and see how they interpret and understand it. Listen to their feedback. Way too many developers don't (I'm looking at your Google!). Wikis are supposed to address this, but don't seem to engage enough people to actually contribute.
Re: (Score:2)
That said, in both case it's actually almost impossible, because whoever you're writing the code and/or documentation for wants you on the next
Re: (Score:3)
I am a tad arrogant, but that is not the problem here. Good Documentation isn't hard, it is time consuming.
It is time consuming because you have to use it, and test it, and revise it for cases you never thought about. Writing itself isn't hard. Getting the writing usable is just time consuming.
IF you don't put in the time, the writing isn't going to take care of itself, and therefore only appears "hard". Sometimes, it seems the best skill I have is patience ;-)
If you do enough Documentation, you can get muc
Re: (Score:3)
Re: (Score:2)
It's not hard to be ambiguous in the English language, special care (as well as a desire) needs to be taken to be clear and concise. Not my best example, but off the top of my head, when people say something like "Everyone is not right-handed", with the intent to mean that some people aren't right-handed, they don't realize that their sentence literally means that NO one is right
Re: (Score:3)
Good documentation takes special skill - you have to write it in a way that's easy to understand as well as being advanced enough to be useful.
Re:OSS needs technical writers more than coders (Score:4, Interesting)
I once took over from a guy who left me a 400 page binder. He must, presumably, have spent some time on it.
It was brilliant if you wanted to know what program fiddlydiddly did or what table doodlefoodle controls, i.e. bottom up.
if you wanted to work top down, i.e. you need to find what causes a specific thing, it was worse than useless.
Re: (Score:2)
It isn't hard to write good documentation. It just takes time.
Good documentation IS hard. That's why there is so little of it.
The biggest problem is that so many FOSS coders can't think of anyone apart from themselves and only care about the fun part - not all the stuff that needs professionalism. They are unable to put themselves in the position of another human being, approaching their "baby" and they have no comprehension, whatsoever, of the assumptions they are making or what they tacitly expect the reader to already know.
As an example, there are many - maybe
Re: (Score:2)
As an example, there are many - maybe even the majority - of FOSS websites where the entry page has no explanation at all of what the program / app actually does.
This! A thousand times this! Sourceforge should ban any project where the contributor can't even bother to write a paragraph on what the software *IS* and *DOES*. So often, you have to play Sherlock Holmes with a list of bugfixes to try to figure out who/what this software is even for.
Re: (Score:2)
From the article: ... there are some amazing books out there that you should read if you care about this stuff. First, I'd recommend Conversation and Community, by Anne Gentle. And if you're looking for a conference about this stuff, there are two that I'd suggest: Write The Docs and OpenHelp.
Write an article (Score:2)
(Seriously though, his section on where is kind of interesting).
Old DOS Borland Developer Tools. (Score:4, Interesting)
I was able to teach myself Pascal and C++ with the quality online Documentation in the Old DOS Borland Developer tools.
There are levels to the documentation.
Theoretical: Why is it here.
Actual: What does it do
Physical: working examples.
Re: (Score:2)
In the same vein: QBasic help file. Until I was able to finally obtain a copy of Turbo Pascal in high school, QBasic was there to teach me programming from absolutely nothing.
Re: (Score:3)
I initially taught myself Commodore BASIC v2 from the reference manual. That was my first programming language, and I was a very small child of 4 at the time. Clearly, that was a well written manual. I also have fond memories of QBASIC (yes, fond).
Shortly after, I had the aid of some series of books aimed at children, which taught BASIC. As I recall, they were slim red hardcover books, and one of the examples included a little racing game. I wish I could recall what they actually were titled, as I'd love to
Re: (Score:2)
I taught myself assembler from a MOS technologies 6502 reference manual and an Apple ][ ROM source.
Re: (Score:2)
Re: (Score:2)
Counterargument: OpenBSD (Score:2, Interesting)
How can your theory explain that one of the best documented projects is developed by the most widely recognized assholes of the open source community?
Re: (Score:2)
What does 'old what's his name' (the toejam eater) have to do with BSD?
Re: (Score:2)
Yes, there are plenty of counterexamples. And those communities - I presume you are referring to Linux? Or did you mean something else? - are remarkably hard for beginners to break into, unless they display a similarly belligerent attitude. Thus, this kind of attitude is self-perpetuating, and it makes it remarkably hard to improve the tone of the community over time. Monkey see, monkey do.
Look, I'm not declaring this to be a theory or a law of community organization. I'm saying that when you're nice to peo
What manual? (Score:2)
The trend nowadays is to sell you a separate book in place of the manual that should have come with the product in the first place....
Love me some FM (Score:2)
The fine `man` has served me well over the years. At points, it is too terse or too verbose, but very rarely is it flat-out wrong.
As for other projects, that's what source code is for, right? No programmer worth their salt should be afraid to dive into a random piece of code to answer a question. It's an essential skill to go from having a question to finding the implementation details and understanding them. Often, this is the only way you get a concrete answer.
Yes, I write documentation for my stuff. Yes,
Re: (Score:2)
If people spent a mere 5% of the time they spend coding an API designed to make something easier, on actually documenting that API, then their actual goal of making something easier would be more effective. Time is money, and the more time people have to waste "re-inventing the wheel" of merely learning
Re: (Score:2)
Dive into source code? Maybe my time is more important that sifting through poorly structured directories full of 500 source code files each, and the 8000 instances of that variable that grep reported back.
I don't go using pieces of software with 500 files and no documentation if I have any say in it. If you spend all your time cobbling together enormous stacks from hugely bloated libraries with no maintainer, you might run into that issue. If you don't have any say in it, you should try ack. It's like grep, but much more useful for source code.
How many times have you downloaded a project, only to discover they didn't even give you instructions on how to compile or link the damn thing in your project? How many times have you seen a project not list their dependencies so you get to play a 15 minute game of "find the packages"?
Many times. I am also good friends with `rm` and `apt-get`. If it doesn't explain clearly how to link against it, or it isn't obvious, I'm unlikely to spend a large am
Re: (Score:3)
If you spend all your time cobbling together enormous stacks from hugely bloated libraries with no maintainer,
So, in other words, the real world?
Re: (Score:2)
"man" pages as an example of good documentation? Dear God Almighty, man, it was going to be my example of the WORST documentation ever created. In fact just about everything associated with UNIX or *nix documentation is absolutely the shits.
The best documentation of that type is VAX/VMS "help ..." The best written manuals of that type were for VAX/VMS, too. Everyone should have to read "VAX/VMS FORTRAN Programmers Reference guide" and go through every single command in > help ...
Oth
The best manuals (Score:3)
Truism (Score:2)
When discussing documentation if thought about this rule:
90% of people want to have documentation
50% of people want to read documentation
10% of people want to write documentation
I think the above is the reason people don't write documentation. Few want to write documentation and they are often not motivated to write because people barely read documentation even if the see a need for it.
Re:Truism (Score:4, Insightful)
10% of people want to write documentation without getting paid to
FTFY. Everyone on an OSS project wants the front-line job of coding (and are even willing to do it for free). No one wants to be the guy doing the hard, less cool but no less essential, job of writing the docs.
Re: (Score:2)
This is a good observation. Perhaps something like Wikipedia, which has been a big success of written "documentation", draws from a very large user base, so the small percentage of people who write still results in a lot of text. It also has a very low barrier to contributing (or at least used to...) For example, I've contributed a large number of small edits to Wikipedia over the years but have never actually written an article, except one I started about some short-lived, long-forgotten David Pogue TV
Bullet Physics (Score:2)
The first hint that it's shit is that the Documentation link goes to a wiki. It gets progressively darker after that.
Prioritize example usage (Score:2, Insightful)
An important area to concentrate on is providing example usage. The more, the better.
Language, Density, and Whitespace (Score:3, Funny)
What I've learned from decades of reading professionally-written manuals can be summed up in two steps:
The first step in writing a good manual is to have a very weak grasp of the language used by your target audience. It is important to use many grammatical and spelling errors, just to make sure the reader stays on their toes and pays attention. Research has also shown that users do not like to read manuals that use advanced vocabulary or complex grammatical structures.
The second step is to manage the density of information on the pages properly. A piece of paper is pretty large, and so are most screens, so a lot of information can be included on a single pane of view. It is important to make the most of this space and convey as much information as possible, as densely as possible. The more information a user can see without having to turn pages, the better. Use of separating devices, indications, and other correlative marks should be avoided, as it takes away from space that can be used for more information. They also can cause there to be more whitespace on a page, which should be avoided at all costs.
Recursive (Score:2)
Story time, my method. (Score:5, Interesting)
So years ago I was in varying positions at an ISP, but regardless of title "head tech" pretty much applied. We kept getting kids right out of high school that claimed to know computers well but had never used a command line, didn't know what an IRQ was etc.. As this was the Windows 95/98 era and this was a dial-up ISP some manuals had to be written.
I of course wrote them.
I made flow charts for email troubleshooting (I hated Visio so I used a graphical editor instead), I had grids for IRQ/Address settings, I had step by steps for undoing AOL I.P. stack sabotage (how many of you remember that?) Fact was I wrote really good documentation that anyone from teenager to adult could use to troubleshoot the "normal" day to day issues a worker at an ISP faces without making a condescending script. If you used it for reference it was an answer key, if you read every word you often would know why that problem occurred. I'm of the belief understanding an issue is always better than just knowing what the fix is.
Long story short - the documents leaked out of the company. On the north side of town there was a help-desk outsourcing company that tended to have a lot of employee migration with our own - in both directions. A buddy of mine went to work at a different ISP and saw my documents turn up there with my name replaced on the credit line (he knew I wrote them - he watched and knew the marks I put in things that were dead giveaways it was my stuff).
I no longer worked at the old company and was still finding out about my documents leaking all over the damned place. I decided to put the documentation GPL on the things and throw them out on my webserver. If figured if I put them out on the web myself then there was a verifiable copy out in the wild, it would shine a light on the plagiarizers, and I was hoping to maybe get offered jobs or something. Later I was criticized with "that really should have been Creative Commons". Fuck you, I did this before Creative Commons even existed.
My web server and the backups were physically stolen from my home, but there's still an archive [archive.org]. To this day I still write in the "explain it, don't step it" method.
Turns out lots of places want idiot guides [slashdot.org] and don't care to understand.
Re: (Score:2)
Re: (Score:2)
One of my favorite things about the job I referenced is most of the people we hired were in their late teens or early 20's and were eager to learn and prove themselves. To this day it's still the age group I like to work with the most. Of course I expected a lot of churn, I would have been disappointed at my trainees if they didn't ditch that place after some training.
I love interactive documentation - I find myself hovering my cursor on a regular basis on stuff I'm unsure of and I'm always disappointed w
The best (Score:2)
How not (Score:3, Interesting)
I am already happy when the author has read http://www.xkcd.com/1343/ [xkcd.com] and some early manpages of sudoers (imho the worst, by far).
Todays "sudoers" manpage has already been cleaned up a lot and is still a horrible read. But in the past it was something like "the relevant configuration is a hierarchical list of geometrical weighted values. Each one represents a position in a list relative to its anchor". And yes, that was just a weird way of saying "/etc/sudoers contains configuration keywords with options".
Overall I had the impression the author was a sociopath showing off his mathematical skills while keeping the core knowledge unavailable to others.
Documentation Requirements (Score:3)
Based on the work I did in 1985 at Bell Labs as part of my assignment to create documentation requirements for the Acorn Network Control System -- Good documentation should have at least 4 parts. Each particular user persona would use the 4 parts in different ways. Part of the documentation would appeal to potential customers, novice users, intermediate users, users with limited but deep domain expertise, users who previously had fluency with the product but who lost that fluency due to lack of use.
#1 The first in additional to typical table of contents found in each manual there should be a documentation MAP, that combines all of the various documentation and training for a specific product into a visual map; typically this is done with a task orientation. Much like a web page site map, this will allow a potential readers with a wide range of user cases to find the right document or the correct chapter, section, and should include online training, videos, Etc.
#2 A quick reference guide which I think most users would be familiar with. This instruction is typically very linear, and walks at a high level users through the major steps for the most typical cases.
#3 A "cook book" best for coding applications but has broad application to most technologies. Each section of this manual details how to perform a particular task, in it's entirety; e.g., a recipe. Recipes should cover a range of users types (novice, intermediate, expert, or with specific previous domain expertise). A non-coding example would be: Recipe for setting up a mix minus recording using the Behringer Xenyx 1202fx mixer; the ingredients would include all cables, software, Etc. used in the recipe.
#4 A complete and full reference guide. Again typically found in manuals but often (today) the ONLY section of the manual. Each sub-section is a full and complete deep dive on each part, instruction, or option. This is typically used by experts. It can be used by those who are using the cookbook to look for recipe options and substitutions. It can also be used by potential customers to see if a particular use case is supported.
Ditch the Passive Voice (Score:2)
Re: (Score:3)
That should read:
Passive voice, should not be used.
Re: (Score:2)
This is a good point. And it's something that technical writers seem to have developed a love for (the passive voice) for some unfathomable reason.
Back when I used to write engineering documentation for Boeing, management used to throw a hissy-fit whenever someone would use the active voice. By hiding the subject of a sentence, it was felt that responsibility for some action or decision could be side-stepped. (See how that reads?) "By using the ACME brand fasteners, it is believed that the wings could fall
Old GNU project manuals (Score:2)
Old GNU project manuals are VERY good. Bash and libc have incredibly detailed and clear manuals (in the form of info files, also available as pre-formatted PDF books). I think no one now writes documentation like that.
As in most teaching situations ... (Score:3)
... it's important to remember what it's like to not know.
Overview, Example, References (Score:2)
The best documentation I have dealt with start with an overview of the process you are going to go through, shows a non-trivial example, and only then going into the jargon filled nitty gritty references and details.
Way too much documentation only covers the detailed references with no clear context or useful examples. Folks in the know are prefectly happy, but folks at the bottom of the learning curve end up very frustrated.
Man pages are the worst. (Score:2)
I really think whoever writes into these has no idea how to make them human readable.
I couldn't be bothered most of the time and ended up googling for what I needed to do instead.
Open source documentation challenges (Score:2)
Open source code faces a special obstacle when it comes to quality documentation. By the very nature of the ecosystem, open source projects derive from the needs of those who are directly contributing to it; the experts, in fact, and thus any artifacts the project produces will be based on their requirements, not those of casual users. It's not only required, but expected that in most cases, a user will be knee deep in the lower level details and have a high level of proficiency and knowledge of not only
Symbolic Links (Score:2)
I remember when first getting into Linux, I had a HORRIBLE time figuring out what 'ln' (link) did, cause all the docs skipped around defining it.
I wrote up some real world docs way back then and they turned into one of the most popular posts of all time on my site:
Symbolic Links: Defined [messagebase.net]
PostgreSQL (Score:2)
Hands down excellent. High-level overviews, more detailed usage guides, fully-detailed references, and internals. Well-written, well-organized. And guess what else? A TABLE OF CONTENTS at the root, so as soon as you find your way to the docs, you can see what's there and how they're organized. Too many OSS projects lack that. (Oh sure, there's tables of contents, lots of them, for individual areas of documentation which are spread all over the place--not the same thing.)
A Lot of Software Defies Easy Explanation (Score:3)
And not because it has to be that way. The software is just poorly designed.
In an ideal world, user documentation would be written before the software so that an understandable, consistent, UI would exist. This sometimes happens, but even then, the implementation may not match the documentation (yes, I have seen this more than once).
Design principles like: simple things (and common tasks, even if not exactly simple) should be simple to do; the same technique should work in all contexts; etc. are often ignored in OS projects.
I have come to despair in trying to find a nice open source (Linux) object-drawing program that is intuitive (and thus easy to learn), has consistent behavior, and allows the quick creation of clean basic diagrams, and maybe has an additional level of finer controls for more precise work. The original Macintosh had this back in the 1980s with MacDraw, and the even more awesome MacDraw II. Complete novices could take the program and discover how to make good looking "boxologies" in minutes just by playing with the tools. Maybe such programs are still available on the Mac platform (I haven't had one in years), but no OS object drawing or 2D CAD program on Linux seems able to grasp what one of the first such pieces of software on the market was able to accomplish.
(Another really annoying thing to find in user documentation is self-praise about the product and accompanying documentation: making promises about how great the product is, and how wonderful the documentation you are looking at is, that are rarely kept.)
Re: (Score:2)
This sometimes happens, but even then, the implementation may not match the documentation
I disagree that it sometimes happens. Writing the manual before you write the code pretty much guarantees the manual will have little correlation with the code for all but the smallest applications.
Re: (Score:2)
I actually agree with this. The documentation does need to evolve with the implementation, and if you don't, it is as you say. But having a clear concept about how it is to be used, and working out a coherent description of using it is a very strong design tool to make a usable, understandable system.
Ask the users. (Score:4, Insightful)
The problem with a lot of documentation is that they aren't written from a user's perspective - they are written by people who wrote the software, and know what to do. Letting go of your design assumptions is almost impossible.
I have long felt that the first draft of documentation must not be written by the person who wrote it; you have to allow your users to "send" you the first draft (either through email questions/screenshots/etc.). Then you realize how many assumptions you made that are non-obvious to your users.
Obviously, this isn't really practical for OSS - you might not be able to pay for usability testing and feedback. Which is why I prefer to include screen shots in documentation as much as possible. Also, I try to follow this basic formula for documentation: What (what is the user trying to do - make it clear what this section of the documentation address), How (how can the user achiever her goals), Why (this is where you might, if you choose, try to explain a design/implementation philosophy - it comes third, so that someone who doesn't care doesn't skip the entire section. Clarity and brevity are important.).
This is the principle I follow for user stories as well - create an end-to-end user workflow (which is basically just many small What/How/Why sections tied together).
Egoless Documentation (Score:2)
Which I had published in the now-defunct SysAdmin magazine in '06. http : //24.5-cent.us/egoless_docu.html
mark
A larger view (Score:2)
For a comprehensive look at what can be done with a very unusual language, the J essays are hard to beat: http://www.jsoftware.com/jwiki... [jsoftware.com] . They provide context around why you might want to do something one way rather than another and are much more literary and wide-ranging than typical documentation.
The details of the vocabulary - linked to from the "Vocabulary" page (http://www.jsoftware.com/jwiki/Vocabulary) are also pretty good because they combine general definitions with explicit usage examples.
The Macro Picture (Score:2)
The very best documentation I've ever read --- and I suspect was written by engineers --- was the Perkins-Elmer OS 8/32 Processor Manual --- once this was read through and through (took me about 50 times) one completely grasped and understood the operating system at the hardware level/software level --- truly a
Understanding. Achievement. Reference (Score:2)
Perl man pages (Score:2, Informative)
One of my favorite sets of open source documentation are the perl man pages. They are written in an informal yet instructional style, and are *loaded* with useful, practical examples of how to use the language. Heck, I refer to "man perlretut" even when I'm not using perl, but I need a general reference for regular expressions. Sooooo useful!
My technique (Score:2)
What's the best example you know of for open-source documentation?
It's not open-source documentation, but the same general principles ought to apply. Years ago I bought an Epson dot matrix printer. The first chapter was called "Quick Start." Quick Start told you how to get up and running with the minimum of fuss. For example, it said, "connect all the cables" instead of saying, "connect plug a (pictured) of cable monster (pictured) to jack b (pictured) of printer 345DEF (pictured), along with all the wa
Maybe it's part of new trend to not have manuals (Score:2)
Re: (Score:3)
I've found later literature to not be as well written, and I've found many projects that aren't well documented at all, like the various GUI windowmanagers and login managers lately.
I suppose this bias toward old, good documentation is contributing to my dislike of Systemd, I don't see the same docs for Systemd that I saw for System V
Re: (Score:2)
Re: (Score:2)
RTFA!
Re: (Score:2)
"RTFM" is defined in the first sentence of the first paragraph of the article.
Re: (Score:2)
Re: (Score:3)
For everything else, there's MasterCard.
Re: (Score:2)
The only technology that never needs a manual is the technology that no one ever uses.
Re: (Score:3)
The Arch documentation is excellent.
Much of the Gentoo docs are really good, too.
Re: (Score:2)
Videos have their place, I grant. Especially when it comes to manipulating some object (could be a graphical object on a screen), where a verbal description just cannot compete.
But I hate "video documentation" with an undying passion. They have an extremely so rate of information transfer, typically very low information density (see how little text is in a 5 minute video script), cannot be scanned at all, require you to have an audible audio hook-up, cannot be copied for notes,... I'm just getting started h
Re: (Score:2)
Good documentation is typically not written by "most coders". It's written by writers. Some of us do indeed get a thrill from writing good documentation. I've been doing this for 20 years because it's fun, not because I'm paid for it, in much the same way that you have been coding, because it's fun. Different people find different things fun. The trick is to make it easier for these kinds of people to get access to the communities which are typically coder-dominated. (As you might guess, there's more about
Re: (Score:2)
It's possible for a programmer to write good documentation, but only if:
1. They're writing it for other programmers, preferably ones already familiar with the product.
2. They're able to think like a non-programmer.
#2 is very rare, IME.