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."

Comments

Docs vs tutorial

[dfsmith]

There's a difference between a tutorial and documentation? Who'd have thunk!

Re:Docs vs tutorial

[lgw]

WHile the difference between a textbook and a reference manual should be obvious to all, TFA still has a point: good documentation should include both.

Most docstrings I see are worthless: they add nothing to the code right below them. OTOH, a bit of tutorial-style documentation with examples can be golden. Often that makes well-written unit tests the best docs, or at the very least, if you're going to provide examples, they should also be unit tests - another test is always nice, plus you know your examples actually work.

Re:Docs vs tutorial

[denmarkw00t]

plus you know your examples actually work.

I've hit this so many times...I go back to documentation after I've made substantial changes to a class and test the documentation - often it breaks, and either the docs get updated or the class gets fixed. Caught many-a-bug just doublechecking my work against how I thought it should work.

Re:Docs vs tutorial

[condition-label-red]

Docstrings are what you *INTENDED* a block of code to do; and the code itself as what you *ACTUALLY* did. Normally the two should match, and when they don't....

Re:Docs vs tutorial

[dgatwood]

There's a difference between a tutorial and documentation? Who'd have thunk!

Actually, no there isn't. A tutorial is one type of documentation. Tutorials are documentation for processes. Non-process subjects require other approaches. It is important to write the right types of documentation based on the likely audience and the subject matter.

I disagree with many things in this article, not because the points are invalid, but because they conflate misuse of tools with low quality of tools. For example:

Wikis are great tools for writing documentation. They make it easy for people to fix minor errors when they notice them. They make it easy to collaborate on documentation without having to deal with the relatively high overhead of source code version control systems (which are particularly awful when merging structured content like XML and HTML).

What the author is complaining about is not the wiki, but rather the fact that those projects have no one who is responsible for maintaining the documentation. If no one is responsible for writing the docs and ensuring their completeness, the documentation will inevitably be half-finished, whether they use a wiki or some other mechanism. The wiki is not an alternative to writing documentation, but rather is a tool for creating documentation.

Doc generation software is great for writing reference documentation. By placing the content into the source code, it becomes the responsibility of the programmer to update any behavior changes when they modify the behavior of a function. It also means that the documentation for the function is easily readable right there in the source code when you're trying to understand a function. By producing the generated documentation, you then have a convenient reference for all your functions, methods, classes, data types, etc. that is readily searchable, indexable, and (perhaps most importantly) is viewed in a separate app or window from your source code so it doesn't force you out of your coding flow when you need to look something up.

Once again, what the author is complaining about is not the doc generation tool, but rather the fact that those projects have no one who is responsible for writing the documentation. When used properly, the output of doc generation tools is every bit as good as documentation produced by hand. However, it takes exactly as long to write that documentation in the source code as it does to write it in a word processor. It is not a tool for saving time, but rather a tool to aid in maintaining consistency between behavior and documentation.

To do software-generated documentation correctly, you need to add comments that explain every field in every data structure, every class, every function or method, and for particularly complex functions, even documentation for many of the local variables. You should write code in your build system to warn about undocumented methods and data structure fields. For example, in one project I regularly work on, there are almost 17,000 lines of documentation comments out of just shy of 59,000 total lines of code—a whopping 28.8% of the total code volume. The result is that it is fairly easy to learn what each piece does in the context of the code while you're looking at it, and the automatically generated documentation is pretty thoroughly fleshed out reference documentation for the project. One particularly complex class by itself produces a whopping 72 pages of reference documentation.

The problem that folks run into is that they usually don't put in any doc comments at all, or at best don't actually take the time to write the thorough comments that are needed to make the output from automatic reference documentation tools be useful. As a result, when you build the reference docs, you end up with an empty skeleton that isn't of much value at all. This is not a flaw in the tool; it is a flaw in the development team. They didn't take the time to write the documentation.

And so on.

Re:Docs vs tutorial

[Anonymous Coward]

... the only thing worse than no documentation is misleading documentation.

Re:Docs vs tutorial

[gsslay]

Have to agree, the hate he's giving Wikis is entirely unjustified. Wiki's are a tool. If you give a group a pen and a stack of paper, and they produce an unreadable mess, is that the pen's fault? Wikis are no different. Approached the correct way, by people who know what they are doing, they are an excellent method of creating quick, consistent and adaptable documentation.

Of course, if you don't have anyone responsible for writing the contents of the wiki, no standards, and just leave it open for anyone passing who takes a interest, then you are going to have problems. It'll end up inconsistent, sparse, out of date and waste of time. No-one will read it and no-one will write anything worth while in it. Good wiki content doesn't just happen.

But if you have people whose job it is to write documentation, and who want to spend most of their time concentrating on content, rather than on the publishing process, version control, file formats, browser compatibility, CSS templates, etc, etc, then a wiki is totally the way to go. There are other, excellent, tools for writing online documentation, but none I've encountered are anything like as fast and easy to compile and maintain as a good wiki.

Re:Docs vs tutorial

[gsslay]

See, if this was a wiki I could go back and edit out that annoying apostrophe that sneaked into my second sentence.

Re:Docs vs tutorial

[khakipuce]

Documentation should be tested. You test your code (I hope) so why not test your documentation??? Like all testing the very act of thinking about how to test it will make you improve it. Then developing documentation tests will help you improve it further. Testing the documentation will further test your application (sometimes what si written in the docs is right but the app doesn't do it).

Give the applicaiton and the documentation to someone with suitable skills but no knowledge of the application and give them some tasks to do. If they can complete the task with the documenation only then great. If they ask you a question, fix the docs. EVEN if the answer to the question is in the docs, if someone asked you then it's not obvious so fix it.Find out what steps they took to find the information and put it in the logical path.

Re:Docs vs tutorial

[davide marney]

The problem is that documentation in code is documentation of code. It helps people writing the code, but not those using the output of your code. To do that, you have to teach.

Re:Docs vs tutorial

[geminidomino]

What the author is complaining about is not the wiki, but rather the fact that those projects have no one who is responsible for maintaining the documentation. If no one is responsible for writing the docs and ensuring their completeness, the documentation will inevitably be half-finished, whether they use a wiki or some other mechanism. The wiki is not an alternative to writing documentation, but rather is a tool for creating documentation.

That does seem to be the standard method in which wikis are used for documentation.

I've felt the author's pain, and have learned to share his hatred of wiki-as-docs. Mostly thanks to this Blender tutorial and most of this Minecraft mod API.

Wiki docs seem like the perfect fit for things which are updated frequently, until you start to see that only half the information is accurate anymore, and half of it isn't accurate yet; because, say, you're using an older version since the new one isn't stable/compatible yet
(i.e. Blender w/niftools). Unless there's a way to view the historical version of a wiki as a whole, instead of popping through revision after revision trying to guess by date when 1.5.1 became 1.5.2 and finding the info you needed.

No thanks.

Re:Docs vs tutorial

[Anonymous Coward]

Hmm, interesting idea. What if slashdot comments were wikis? Would that eliminated the FTFY comment? Instead of comment wars, we would have comment edit wars. Sounds fun.

Re:Docs vs tutorial

[Anonymous Coward]

You test your code (I hope) so why not test your documentation???

Probably because you cannot automate documentation testing. After you've written a test suite, running it just means issuing a single command, and when it's ready, look at the results. Testing documentation uses up human time. Human time is valuable, and many people seem to undervalue the documentation, therefore little human time is allocated for that.

Re:Docs vs tutorial

[dgatwood]

True, but my point is that you need both. The documentation of the code is orientation for people who intend to modify your software. User guides are documentation of the behavior of the software as a whole for people who merely intend to use the output of your code.

Re:Docs vs tutorial

[dgatwood]

On the one hand, this might be an argument for cloning the Wiki to a separate section when you do a major version branch.

On the other hand, this might also be an argument for why you need to design your user interface right the first time, so that users aren't completely befuddled when they encounter documentation for a newer version of the software (notwithstanding new features).

Re:Docs vs tutorial

[geminidomino]

I'd rather support the first hand, since the other hand makes two assumptions that I question the veracity of.

1. It's possible to "do it right the first time." There's always one more bug.

2. That good user interfaces are never replaced with bad ones because the company/team/project took on some "UX" bullshit artist.

Re:Docs vs tutorial

[dgatwood]

Fixing one more bug shouldn't radically change your UI design. With regards to your second point, I guess my point was that this shouldn't happen, and if it does, you're doing it wrong. ;-)

Documentation vs Tutorial

[Anonymous Coward]

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.

Re:Documentation vs Tutorial

[snowraver1]

One problem I encounter all the time is what level of competence should be assumed? If I write "try ping host xyz" should I assume they can successfully pingtest something and interpret the results? For ping, yes maybe I should assume that, but what about grep? Grep isn't officially supported by the organization so...

I feel like I'm wasting my time writing instructions for simple tasks, but I also feel that I have to write as I though a monkey is the intended audience. I hate to say it, but it's the godawful truth, that there are too many people in IT that can only read-and-do.

Re:Documentation vs Tutorial

[Anonymous Coward]

One problem I encounter all the time is what level of competence should be assumed?

You've asked the only question that really matters, not only in terms of documentation, but all writing:

Know your audience.

Trying to write one-size-fits-all documentation is as futile as coming up with the single one true programming language. It ain't gonna happen.

Re:Documentation vs Tutorial

[__aaltlg1547]

You don't write the ping documentation yourself. You refer to it in the system reference manual. Somebody already wrote acceptable documentation for ping. You should study the ping man entry in, for example, the BSD user manual to see one way to write intelligble, useful documentation.

If you're advising the user to "try ping host xyz" you need to explain why and what to do if it returns the expected or unexpected results and what conclusions he can draw from them.

Re:Documentation vs Tutorial

[kermidge]

"If you're advising the user to "try ping host xyz" you need to explain why and what to do if it returns the expected or unexpected results and what conclusions he can draw from them."

This.

You can show and tell what and even how all day long to little avail; telling why educates both writer and user and lets one get on with solving problems.

Wikis are better than nothing

[im_thatoneguy]

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.

Re:Wikis are better than nothing

[turbidostato]

"I would rather have unreliable information than absolutely nothing at all."

Quite extrange. I certainly would prefer absolutly nothing at all than unreliable information. Incomplete, vague? That's better than nothing but, unreliable? No thanks.

With no documentation at least I know where I stand but what's good about learning, say, that an API call will return 0 on sucess... well, or maybe it's 1 despite what the documentation says, who knows?

Re:Wikis are better than nothing

[lahosken]

Yeah. I'm a professional tech writer, proud of my skills. But in plenty of cases, source-code-with-docstrings is enough.

I hope someone wouldn't hide away these rough forms of documentation, waiting on some exquisitely-crafted docs that they might never get around to writing. I like what he's saying about organization, keeping in mind how someone's going to learn this stuff. But I think he's setting a high bar.

Any tool can't be the right tool

[Anonymous Coward]

In other news a screwdriver is not the best hammer, it turns out.

Re:Any tool can't be the right tool

[ArcadeNut]

Maybe not the way you use it....

Um, no

[grasshoppa]

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.

Re:Um, no

[Anonymous Coward]

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.

Sounds like those documentation that get in your way are not properly done. Basically the author's premise.

I do agree with your point though, an expert technical documentation does not make. But we're probably just splitting hairs, to some pointy haired boss somewhere, as long as a new developer can read docs and get going to be productive, they may consider them "expert" enough...

Re:Um, no

[jaycvollmer]

Um, yes, but...

Good documentation needs to be able to walk the line between being good enough and exhaustive. Nobody wants to spend a lot of time reading what they would consider pointless supportive text, but sometimes this explanatory thread is the best way to communicate the ideas involved. I'm a former high school teacher who has discovered that I love technical writing. I think that every teacher will agree that different people learn in different ways and through different modalities. I've been writing technical documentation for many years now, and I've always had the most success when I approach each topic explaining it in a way where I present the important 'get out of my way' details for those who aren't helped by supportive text, but also with these features tied together with an explanatory thread for those who are helped by this approach.

Re:Um, no

[Anubis IV]

I've found that it's useful to have a bit of A and a bit of B, since they need not be mutually exclusive, and I think that's what the author was getting at.

If you're approaching a massive codebase, most people need a mental framework to operate within, so have a few documents that lay out the high-level stuff, explain them in general terms, and provide a bit of thinking behind some of the big-level decisions that went into them can be extremely useful to both experts and novices.

As you said, however, no one likes it when the documentation gets in the way, so you really need to have quick reference parts that can provide bullet point answers while going light on the text. Of course, you can also have paragraphs to walk people through examples, philosophies, architectures, or whatever else, but those should be in addition to and clearly delineated from the quick reference portions of the documentation.

Basically, the key is to keep the documentation accessible to everyone. Going too far in one direction to the exclusion of the other is a bad thing, but it's quite possible to write documentation that is both brief enough in the important parts that an expert in the field can get up to speed quickly, as well as educational enough that a non-expert can become an expert in using the software. It may involve having separate sections to your documentation, or else having a quick summary at the top of each section with education details underneath, but it's very doable.

Re:Um, no

[Anonymous Coward]

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 ).

And thus showeth typical tunnel vision. How do you suppose those people get to be experts in the first place? You gloss over that, when it's right in the bit you quoted.

Which sadly is far from uncommon in the software world. There are even really big projects, used by bloody everybody, that think that merely having a doxygen dependency substitutes for writing documentation. Because now you have all the function headers nicely printed in five additional formats... but still no idea what it all does, nevermind how it can possibly work together. Thus I could contend that the common case is actually worse than TFA presupposes, as it assumes someone has tried to write meaningful documentation at all. Yes, there's a lot of failing in that field. More still don't even try.

Xorg comes to mind--and it's a reason people try and reinvent the wheel, like that horrible d-bus botch or the various opaque configuration databases where a reasonably functional network-independent (instead of -unaware) and a both auto- and hand-manageable database already existed. It's also a reason why they keep on failing with their own architecture and why their rewrite from scratch will have the same ailments in the long term. They still haven't figured out how to manage a long-running project: Useful documentation.

All documentation should be doing is explaining the sticky bits and providing details and/or examples ( whichever is relevant ).

It's entirely possibly to provide "details and/or examples" that are perfectly useless except in a few corner cases. That makes the "sticky bits" be a complete lack of coherence, of an overview of what parts there are and how they fit together, and thus the documentation be a part of the problem, not of the solution. Nice consulting job there, boyo.

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.

Yet you have no idea what it means for documentation to be both a thorough introduction and a meaningful reference. The latter means that you can quickly find the relevant bits to your situation, but it doesn't mean it only contains the stuff you really need right now. What you effectively require is the minimal set of all the problems *you* might require, in order of appearance, and that requires the shipper to have a functional crystal ball.

Re:Um, no

[Tsu Dho Nimh]

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.

Definitely NO, and even HELL NO! It's to make it possible for them to use the product at the level they were hired to use it at, or for the purpose they bought it for. My auto's user manual is a USER manual, not a service manual and not an automotive engineering textbook.

Re:Um, no

[Anonymous Coward]

From TFA:

You don’t need to explain things from first principles. Try to put yourself in the shoes of your users.

If your users are experts then tailor your documentation accordingly, but it still is necessary to provide background and high level ideas. If documentation is "getting in your way" - learn to use the search button? While the rest of us less gifted experts try to make some high level sense of what the code is about. And then we can get to the sticky bits and learn why they are sticky.

Re:Um, no

[murdocj]

No. An expert may be an expert in an area, but until he's familiar with your code, he's not an expert in your system. I've spent way to much time deciphering code where a single sentence explaining what the hell the code was doing would have saved time. If you had enough time to write the system, you have enough time to document it. And if it's hard to document, that's a hint that it's a crappy system.

Re:Um, no

[DuckDodgers]

I write extensively on the wiki at work. I can't teach someone else to be as good as I am at my job just by reading books. Outside of the rare incredibly intelligent person, for most learners at some point you have to try things for yourself in order to genuinely understand them.

What I am trying to do is provide a Howto for every task I do routinely. I've got a page of links in alphabetical order with duplicates (i.e. "Database Setup" and "PostgreSQL Setup" both take you to the same page.) Each wiki page is in this form "Step 1: pre-requisites. Your computer must be on the office wired network or connected to the VPN." "Step 2: You must have the following programs installed." "Step 3: Open.... and type or paste the following... " "Step 4: In step 3, if the result was X, go to Step 5. Otherwise, go to step 6."

The goal is to make it so a tenth grader with basic computer skills and reading comprehension can handle all of the mundane tasks and I can be left alone to work on the more advanced projects. So far, no luck. If anything breaks, it's easier to contact me than try to fix it on your own. That's fine right until I turn in my two weeks' notice... which happens tomorrow. I used to worry that nobody else in IT understands what's happening in sys-admin or network-admin roles. But I spent the last three years putting a step-by-step guide for just about everything I can think of down, and asking and later begging people to try it out and report errors. At this point I don't care any more. They want to test my instructions after I am no longer available to fix errors, that's their problem.

Re:Um, no

[__aaltlg1547]

Seriously, you ARE the problem. You're arrogant and fucking lazy.

Fuck the users if they don't already know everything there is to know about everything. They should already know how to use my code even thought I just wrote it and it's novel and interesting and they should be honored just to have the privilege of using my code. Who do they think they are to ask what it's for or how to use it or how it handles errors?

Re:Um, no

[simishag]

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).

I completely agree but how are we even calling this "expert" or "professional"? Do I need to educate someone, a "programmer" let's say, about the fundamentals of Java? About electronics? About physics? How to type? How to use the toilet?

Maybe that's over the top, but at some point, if someone claims they can do X, we assume a basic level of skill. To use a car analogy: cars basically all work the same way. The car dealer doesn't make you take a test before you buy it and drive it home. They have to make sure you have a valid license, of course, but licensure is not their problem, and licensure by the state assumes that the basics of driving are the same across different models of cars.

Re:Um, no

[zippthorne]

All experts need to learn their expertise somehow.

An expert in using software that you have just written is going to need some kind of documentation from you on how your software works. They're going to need thorough documentation, and you're going to need to assume they've never used your software before, because you've just written it and no one has used it yet.

Re:Um, no

[CAIMLAS]

I have worked in and around many environments where no degree of clear documentation would help due to how completely brainfucked the implementations are. Despite the tombs of very thorough documentation, they're still a goddamn mess. Even the high level overview has caveats and exceptions of how it works, where it works, etc.

Hell, pick an operating system. You typically need at least a high level overview of how it works before you dive in: "This is UNIX. We use pipes and redirects, and everything is a file. Go."

Now, a system which follows best practices? Absolutely, there should be no 'teaching' required, assuming it's of moderate complexity. "x happens when y occurs in certain scenarios" or the like. But I've rarely seen an environment which even approaches 'best practices' because status quo just-get-it-done has been the order of the day for entirely too long, and people are lazy and/or overworked.

This is coming from the systems/network side of things, often in environments which are developer centric (and historically 'managed' by the devs). Custom applications cobbled together for functionality across a dozen hosts with half a dozen scripting languages over a period of a decade... it's a nightmare, and frequent.

As someone who has invariably come into environments with little/no usable documentation, and have since been thanked several times for leaving behind such useful documentation (yes, in wikis), there's a time and a place for documentation. High level things (need, purpose, etc.) as well as 'gotcha' specifics are useful.

Re:Um, no

[Anonymous Coward]

Hence the "expert user". Not an expert in everything there is to know about the system, and how it works. But a top notch *user* of the system. Good documentation of a program, say grep, or ack, or systemd will be able to take someone who's never used the tool and turn them into a user who is profficient and is able to use the tool to its fullest.

Expert here refers to specifically the use of the system.

Re:Um, no

[Anonymous Coward]

What is "moderate complexity"? Every system will require some learning. Maybe you can learn it by looking at source, or doc strings, or whatever. Not everyone learns that way, not everyone can grasp that level of complexity instantly. I doubt even you can figure everything out about something..

Just because you might not *need* great documentation to use something doesn't mean it hurts to have it...

Also, no one follows best practice 100% of the time.

Re:Um, no

[RobertLTux]

and to stay with the car thing you might want to make sure that the list of the 12 things that engage the self destruct system are in the manual and the small fact that the gearshift is BACKWARDS (and if you push the shifter while its in the normal PARK position thats number 8 on the previous list)

Re:Um, no

[im_thatoneguy]

I've spent way too much time trying to decypher my own code a year or two later. :D

Documentation isn't even just for other people. I've been trying to update an Python package I wrote last year and I couldn't make heads or tails of its proper usage for a couple days. I even started adding a feature that I felt was obvious and missing until closer inspection at the code reminded me of the intended mechanism to handle that class of scenarios. A simple little 3 line comment with an example or two would have cleared that right up.

Sigh

[Anonymous Coward]

Programmer Steve Losh has written a lengthy explanation. . .

And we're done.

Examples Examples Examples Examples

[Anonymous Coward]

Provide that in addition to docstrings, and you will make everyone satisfied.

Re:Source code

[Entropius]

Do you really want to read the source code for ssh every time you forget whether it's -p or -P to specify the port? (It's one for ssh and another for rsync...)

I don't get it :p

[Anonymous Coward]

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...

Re:I don't get it :p

[Anonymous Coward]

The point is that "technical documentation" needs to include *both* these things, but too often the API docs are treated as "the tutorial".

Re:I don't get it :p

[dkf]

If you want to learn to program you want to read tutorials not the API documentation...

And if you're wanting to maintain the system, you need the API documentation and the technical architecture overview. Occasionally that's put in the API docs, but it's very rare, and the tutorial hardly ever touches on the architecture (they serve different purposes). The purpose of the architecture docs are to tell you what the overall purpose of different APIs are, where you look for implementations of certain types of functionality, and how to fit the pieces together; such stuff is usually non-obvious even with quite a lot of expertise, as there are frequently many different ways to achieve the same thing. Moreover, the bigger the application, the more you need such high-level views to help you find your way around.

You'll probably be referring to the API more often though.

Re:I don't get it :p

[davide marney]

His argument is that a lot of people just produce reference materials and claim they've "documented" the system. Proper documentation needs both tutorial AND reference.

Reference manual

[Anonymous Coward]

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.

Re:Reference manual

[hedwards]

Some people? Unless the developer has gone out of his way to make the basics self explanatory, nobody is going to become an advanced user without one. Unless of course your program is the only one that does what it does.

I was screwing around with Kdenlive a couple days ago, and it completely lacks any intuitive way of cutting files up. You can save zones, but I have yet to find any corresponding restore function. And there isn't any obvious way of cutting sections of a clip out other than just the first clip you do.

There presumably is a way of doing it, but without proper documentation a person is never going to figure it out. I haven't read the documentation yet, so I don't know if that's going to help, but good luck caring enough about the software to get to the point where tutorials aren't mandatory.

As a tech writer of decades

[Anonymous Coward]

Thanks for pointing out what we've been telling developers for as long as there have been tech writers.

In other words...

[vuke69]

...the author doesn't understand what documentation is supposed to be used for.

Driver's Manual

[Anonymous Coward]

Am I the only one who enjoys reading the entire owners manual when you buy a new car?

Re:Driver's Manual

[dfsmith]

My last owner's manual was about 400 pages; but contained only about 10 pages of useful information.

Re:Driver's Manual

[m00sh]

My last owner's manual was about 400 pages; but contained only about 10 pages of useful information.

10 pages of useful information to you maybe. Other people will find some other 10 pages useful.

My mathematics textbook is 600 pages but there is only 1 page with the information that I need to solve a problem. Doesn't mean the book has only 1 page of useful information.

Re:Driver's Manual

[dfsmith]

My mathematics textbook is 600 pages but there is only 1 page with the information that I need to solve a problem. Doesn't mean the book has only 1 page of useful information.

Wow! Did your textbook contain 599 pages of "this equation is not designed to be used in the rain" type of legaleze? B-)

About the only thing worse than car owner manuals is car baby seat installation manuals. These are almost impossible to read because the disclaimers are so thick one can't even find the instructions supposedly within them. There are more red-circle-prohibitions than how-to diagrams!

Re:Driver's Manual

[Anonymous Coward]

You should try a space shuttle toilet manual.

The web and hyper text are a challenge

[EMB Numbers]

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.

Re:The web and hyper text are a challenge

[hedwards]

It's harder, but you can give them the prerequisites at the top of the article along with the relevant page numbers. With dead tree manuals people could always skip the background information. And with manuals that's more likely than with novels.

Re:The web and hyper text are a challenge

[Anonymous Coward]

The challenge with electronic/on-line documentation is that there is no expectation that readers will approach the material in any particular order.

This challenge was addressed about 23 years ago by Tim Berners-Lee. He invented a system whereby one can productively investigate written material in an unordered manner. You can check out successful manifestations of this concept on a system called the Internet.

The belief that things are best presented in a one dimensional, book-like fashion is writer nostalgia and publisher business model. Real learning is discontinuous, which is why usable books have a comprehensive table of contents and an elaborate index, at least. Real teachers never present textbooks in a linear manner; they must always isolate the parts that need to be taught at any given moment, because real learning in real schools with real students demands this.

The effort spent on coercing knowledge into a one dimensional format is wasted. That effort is better spent discovering where specific knowledge fits in the unbounded, demonstrably non-linear network of knowledge and conveying these relationships in a usable manner.

Re:The web and hyper text are a challenge

[EMB Numbers]

As a university instructor, I disagree. Many subjects are presentable in sensible sequence with knowledge neatly building on prior knowledge. The entire curriculum is created with prerequisite and co-requisite courses. Attempting a 400 level class without having mastered the 100 level course content is a recipe for pointless struggle.

Wikipedia is a great resource. It's articles are self contained and generally rely only on general knowledge. Wikipedia is not a good source for delving deep into subjects.

Having said that, I use wikipedia extensively. There is almost an entire Computer Science undergraduate curriculum in there. t still requires a guide. There are still sensible paths through the information. Here is a great example: http://en.wikipedia.org/wiki/Fibonacci_heap In the context of a Data Structures course, that is a great page. What benefit would that page provide to somebody who has never programmed and doesn't know what a data structure is? You can follow links to http://en.wikipedia.org/wiki/Heap_(data_structure) and then http://en.wikipedia.org/wiki/Data_structure and then you are directed to dead-tree textbooks that explain the topics in a sensible sequence.

Re:The web and hyper text are a challenge

[__aaltlg1547]

Table of contents.

Re:The web and hyper text are a challenge

[Anonymous Coward]

As a university instructor, I disagree. Many subjects are presentable in sensible sequence with knowledge neatly building on prior knowledge. The entire curriculum is created with prerequisite and co-requisite courses.

Your job is teaching a predefined curriculum. That's fine for schools, as that's what they are there for.

Out in the work place, people don't have time for that, nor are they interested in doing so. They have a problem that needs solving, and while the knowledge needed to solve that specific problem may be in chapter 17 of your book, the information needed to get that far doesn't necessarily include the entire book. The direct prerequisites may be chapter 14 and 16, with chapter 9 and 10 being prerequisites for chapter 14, and chapter 12 and 15 being prerequisites for chapter 16. Oh, and the user already understands the concepts explained in chapter 10 and 12.

Take math for example. If I want to take the cross product of two vectors, I need the chapters on vectors, and for that I'm interested in the chapters on triangles and angles, and thus sin/cos. The statistics chapters, I have no use for. Yet, in my math book, the statistics chapters came before the vector chapters.

Re:The web and hyper text are a challenge

[AmiMoJo]

When it comes to code documentation the reader is often under pressure to deliver a quick fix to some specific problem, so the temptation to search and just read the bit that seems relevant to the issue at hand becomes irresistible. Unfortunately documentation, no matter how good, can't defend against the PHB.

Re:The web and hyper text are a challenge

[davide marney]

One of the things I like about Sphinx is that it has a just one file per chapter, and every one has a table of contents and links to other chapters. So, even if you land on a page from a search, you still have your navigation.

blurred lines

[globaljustin]

I like seeing this alot:

documentation should be used to teach, not to dump excessive amounts of unstructured information onto a user

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.

Re:Source code

[Anonymous Coward]

Of course I do. Reading source code is guaranteed to be the most up-to-date explanation of how things work. By definition!

And of course this is based on the assumption that people name their methods, classes, functions and variables in a meaningful way, structure their code, and other do all the other things that make it a maintainable code but even if not, what would you rather base your decision on, an out-of-date wiki or a confirmation by seeing with your own eyes?

I can't believe my eyes when I read all those idiotic questions on stackoverflow.com such as "what if I use this option with this library, will that work?" Then they go via trial-and-error and at the end of it, they still don't know whether what they observed is true or not. Instead of clicking 'download source' in their IDE and fucking checking themselves.

It's not rocket science, it's just code. Code is like any language. It is to be both written and read (except for Perl, which is write-only :-P ).

TFA is stupid and wrong because I say so

[Anonymous Coward]

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.

A common language

[jackb_guppy]

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.

Stack Overflow

[EMB Numbers]

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.

Re:Stack Overflow

[timeOday]

Well, I am going to defend Stack Overflow here, because I think it fills a very useful niche, which is "what is the best way to do X." There is no way that a "single-source" documentation, such as the API documentation or a book, can foresee all those specific questions. I do not go to stackoverflow to search for information, but very often when I use google to search, stackoverflow has the first useful information. As opposed to a straight wiki, what makes it useful is the (slashdot-like) moderation system.

Re:Stack Overflow

[PRMan]

Um, that's why people VOTE on the correct answer. One of the top 2 answers is virtually ALWAYS the correct answer (usually 2 ways of solving the same problem that you can choose from).

Re:Stack Overflow

[EMB Numbers]

The blind leading the blind. People who can't tell good answers from bad upvote bad answers. Try searching for some topic that you know a lot about and see what I mean.

Re:Stack Overflow

[snowraver1]

Sometimes when you are out of ideas, even a wrong idea can be a help.

Re:Stack Overflow

[real-modo]

Well, I am going to defend Stack Overflow here, because I think it fills a very useful niche, which is "what is the best way to do X."

closed as not constructive by XxxxxX Sep 29 '11 at 13:29

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

Re:Stack Overflow

[Anonymous Coward]

People who can't tell good answers from bad upvote bad answers.

Same thing happens here. This is how your previous post got modded up.

Re:Stack Overflow

[turbidostato]

"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."

The one that makes sense, of course.

If you can't see what the proper solution is at a glance, then Stack Overflow may seem that it's for you but, believe me, it's not.

Re:Stack Overflow

[Anonymous Coward]

Sounds like someone couldn't get an answer accepted.

Re:Stack Overflow

[denmarkw00t]

Sorry for all the hate but...SO is generally useful for very specific questions. Some answers apply to general 'how do you do X with Y' but most are "Hi, I have this ton of code and for some reason it's not doing what I thought it would, why not?" That's the point. Many of the 'how do you do X with Y' questions can readily be answered by the documentation for Y, but the first choice for some is to have others just tell them b/c idk - I'd say out of laziness, but creating an account on a website, asking a question, and waiting and sifting through answers seems like more work than just going to jQuery.com and using that little search box.

In the other case, you might glean something useful out of the answer if you aren't the asker, but the problem is likely specific to an application they are developing and you have no context to the code around it. An answer may not look great to you, but it may be just what the asker wanted. If it's the accepted answer, accept it and move along to something that fits what you're trying to do - and if you're just perusing, expect much of what you come across to be "meh" material. If you have a better solution, post it, but don't be upset if it doesn't get accepted over some POS code - know that your answer may help someone else who ends up at that question, but the accepted answer doesn't fit for them. Upvote for you. Yay.

Re:Stack Overflow

[DarkTygur]

Well, I am going to defend Stack Overflow here, because I think it fills a very useful niche, which is "what is the best way to do X." There is no way that a "single-source" documentation, such as the API documentation or a book, can foresee all those specific questions. I do not go to stackoverflow to search for information, but very often when I use google to search, stackoverflow has the first useful information. As opposed to a straight wiki, what makes it useful is the (slashdot-like) moderation system.

How often do you really use Stack Overflow? They almost always close "what is the best way to do X" questions. It's quite annoying in my opinion.

The following were found from a Google search for: stack overflow "what is the best way to"
http://stackoverflow.com/q/6806/229320
http://stackoverflow.com/q/1017017/229320
http://stackoverflow.com/q/74625/229320
http://stackoverflow.com/q/18557042/229320
http://stackoverflow.com/q/244882/229320

Re:Stack Overflow

[Jmc23]

Depends on the community for the language. Perhaps your community just sucks and it might actually be due to the design of the language.

Re:Stack Overflow

[dkf]

The blind leading the blind. People who can't tell good answers from bad upvote bad answers. Try searching for some topic that you know a lot about and see what I mean.

I've seen a lot of things said about Stack Overflow, but this has been something that's consistently said that I've never been able to substantiate. I've seen questions with no good answers where some of the poor ones have received some upvotes, but where there's an actual good answer — something that you can check for yourself because a good answer will be one that includes a description of what to do — it tends to attract upvotes over time. (Which answer is accepted is more variable, as that's the gift of the person asking the question.) While there's a bit of cult following going on (i.e., voting someone up because of who they are) it is relatively rare because most of the highly rated people are that because they tend to give good answers.

Typically, where a question has what you think are bad answers receiving upvotes, that's either because you've misunderstood the question (duh!) or because the question itself was poorly asked. Which sucks a lot but happens. If you think you can provide a better answer than the ones that already exist, then write that answer and don't whine about it! (Bear in mind that good answers can pull in reputational increases over a number of years; one of my answers from 3 years ago pulled in a vote yesterday. It's a long-haul game.)

Re:Stack Overflow

[melonman]

My experience is that I have to read 10 Stack Overflow responses to find one that gives me a clue to the right answer... and that this is still usually a faster way to find a solution than trying to work it all out myself. It's usually one of the "No, that's wrong because..." post that turns the lights on for me.

Re:Stack Overflow

[bingoUV]

Bear in mind that good answers can pull in reputational increases over a number of years; one of my answers from 3 years ago pulled in a vote yesterday. It's a long-haul game.)

Do they pay you for votes?

Re:Stack Overflow

[coolmadsi]

Well, I am going to defend Stack Overflow here, because I think it fills a very useful niche, which is "what is the best way to do X."

Most of the time I use Stack Overflow is after pasting an error message into Google and it coming up towards the top of the results. The responses are usually reliable, although I have found a couple of unanswered questions.

Re:Stack Overflow

[Anonymous Coward]

Bear in mind that good answers can pull in reputational increases over a number of years; one of my answers from 3 years ago pulled in a vote yesterday. It's a long-haul game.)

Do they pay you for votes?

In a sense, yes. Votes affect your Reputation (somewhat similar to Karma on slashdot). And the higher your Reputation, the more things you can do (indeed, if your reputation is too low, you cannot even leave a comment on someone else's question or answer).

Re:Stack Overflow

[bingoUV]

And the higher your Reputation, the more things you can do

Examples? Not of how low reputation harms you, but of how high reputation helps.

indeed, if your reputation is too low, you cannot even leave a comment on someone else's question or answer

And leaving comment helps me how?

I understand dick waving, but is there a point to StackOverflow "Reputation" too?

'help'

[globaljustin]

a difference between a tutorial and documentation

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

Re:'help'

[spottedkangaroo]

Who cares about non-techies? we're talking about API docs. Non-techies likely aren't playing without help from a techie in the first place -- if they play at all.

Re:'help'

[Anonymous Coward]

Whoa there, dude. I care about techies. API docs without the explanations about why are just stooopid!!

I KEEP six honest serving-men
  (They taught me all I knew);
Their names are What and Why and When
  And How and Where and Who.

Notice in Kipling's poem that What and Why have priority over How. I don't give a damn about How until I know Why. Simply looking through the source code won't tell me that in the general case.

Re:'help'

[Macgrrl]

As a BA who gets asked questions on how various systems interact, I get incredibly frustrated in being pointed at source code and scripts to try and figure things out when they should have been documented clearly in the first place.

I say this as someone who has spent the last working day trying to verify how a particular system functions when none of the original BAs, testers or developers are still around and as a result of a number of unrelated events we have zero development staff inhouse for the next week.

Re:'help'

[Chatterton]

That is so true. I have stopped counting the number of library/API I have not used because I was unable to put the pieces together due to bad documentation. I had to use other library with less functionalities but having all the documentation needed to start using them and explaining how they worked. For example, i have chosen to use Guile over Lua (At the time Lua would have been more easy to use for me than Guile) because at the time I made the choice, the Guile documentation was better over how to integrate it with your programs and i did found a list of do and don't explaining what you should do and you shouldn't do. This last point in itself was the best thing ever really saving me from lots of headaches.

Re:'help'

[Anonymous Coward]

As a BA who gets asked questions on how various systems interact, I get incredibly frustrated in being pointed at source code and scripts to try and figure things out when they should have been documented clearly in the first place.

I say this as someone who has spent the last working day trying to verify how a particular system functions when none of the original BAs, testers or developers are still around and as a result of a number of unrelated events we have zero development staff inhouse for the next week.

Maybe your organization should have paid for docs then, before firing or running off the original devs or for a documentation specialist who could work productively in the environment your organization's management has fostered.

Re:'help'

[b4dc0d3r]

Petzold, Prosise. Two examples of good documentation. K&R, a different approach.

Wrox, how not to do it.

Go forth and multiply.

Re:'help'

[smash]

Given that probably 90% of situations are common to every user of a particular app and used 90% of the time, having a "here's how to do the most common thing" tutorial before presenting all of the advanced options most users don't need or care about is probably sane.

Re:'help'

[Anonymous Coward]

And I'd guess you'd be the explanation why most specialized business software is ugly and archaic seeming compared to any other expecting to see a much broader userbase. In most cases nobody expects it to be used without any specialized training.

Thankfully there are others who think different. A lot of the most popular and sucessful commercial or FOSS software is made by developers who understand that total noobs will try to use it and make sure there is a UI (with tooltips even) and enough reasonable documentation to point them in the right direction. You don't get the numbers of sales like Windows or downloads like Open (or Libre) Office, unless people considered tech-illiterates can effectively use them to some extent without spending time having to RTFM before every single step.

Of course sometimes it takes time for the idea to catch on in some software projects, but usually once it does to some degree, the rate of adoption of a given software takes off considering that it becomes more "usable" by a much broader userbase.

Also don't confuse this with dumbing down or "baby-fying" software. Any software that is worthwhile should be able to turn off all the hand-holding aspects and allow users to access settings that risk breaking things in order to do what they need to do.

Re:A common language

[PPH]

peaked before the new developerl.

Freudian slip much?

You Insensitive Clod!

[Anonymous Coward]

I run Windows!

Worst car analogy ever

[simishag]

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.

Re:Source code

[Anonymous Coward]

Do you really want to read the source code for ssh every time you forget whether it's -p or -P to specify the port? (It's one for ssh and another for rsync...)

I usually just write my own ssh and rsync clients. Much faster...

BTW: In rsync -p is the same as --perms and -P is the same as --partial --progress. Neither of them specify the port. You need --port for that. getopt_long() FTW!

Re:Source code

[Anonymous Coward]

I hate you! You're one of those co-workers that urgently e-mails me at 1AM in the morning asking me how to use some utility I wrote. In the morning I reply, "Use the -h switch, you mother f*cker." Followed by my usual disclaimer--"Every utility I write has an -h switch, which describes the switches option-by-option, followed by short description of the function of the utility, plus gives links to additional documentation."

And if you think you're going to find the -p switch in OpenSSH source code, good luck. Option argument handling is strewn about in several different files. I know, because I've had to hack on it and add options, as well as fix the parsing of forwarding option arguments, among other things. I've seen worse, but it's a long way from some utilities, where getopt and getopt_long processing is concise and easily readable.

Pro tip: readable source code has nothing to do with methods, classes, functions, or variables per se. It's the overall structure that counts, even if it's a single 10,000 SLoC function. Most C++ apps are harder to read than a gigantic ASM app.

Most people organize their code by what it literally does--by the components they learned in school or a textbook. They tediously breakdown blocks into a myriad functions and classes based on their algorithmic role. Or they farm out "parse_int", but then have a 200-line chunk of code processing a dozen different kinds of ints (ints for timeouts, ints for userid, etc).

I don't have many simple tips for alternatives. I just know that most people are doing it horribly wrong. I like to think my code is fairly easy to read--and people have told me that--but I know I could get better.

Okay.. one simple thing people could do more often--use fewer source files, fewer classes, etc.

Also, people abstract too early, before they understand what the meaningful abstractions are. So they end up with too many abstractions, creating too much complexity. People should begin to write their applications as quickly as possible, without worrying about structure--just functionality. It's only until you're about one third or even halfway through that you have an idea of how the whole application should be structured. That's when you start over, before it's too late to re-architect, but after you have a concrete idea of what's necessary and what's superfluous.

The rules

[Anonymous Coward]

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.

truer words have never been written

[Gravis Zero]

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*

Re:truer words have never been written

[Anonymous Coward]

While I agree somewhat with the first point (auto-generated documentation indeed makes developers incorrectly think they have proper documentation; however it is not completely useless as, if used correctly, it can still give a good reference manual — it doesn't give you an user's manual, however), the second point is completely off.

A wiki is a tool. Saying "Wikis are the worst form of documentation" is like saying "Word is the worst type of documentation". Both sentences are equally meaningless. You can write excellent documentation using a wiki, or you can write absolutely crappy documentation using a wiki, just as you can do using Word, or Google Docs, or LaTeX. A wiki just makes it easier to collaborate, but it doesn't by itself affect the quality of the result, in one direction or the other. People writing excellent documentation will do so no matter whether they use a wiki, a word processor or a plain old ASCII editor. And people writing bad documentation will do so in Word just like on a wiki.

Re:Um, yes

[Anonymous Coward]

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.

Re:Source code

[snowraver1]

-h? Next time, use all three of these: -?, -help, --help. I'm probably not going to try throwing -h at a program without having a clue what it might do.

Re:Source code

[snowraver1]

Hate to reply to myself, but I forgot /?

Re:Source code

[lgw]

Command line utilities should print their documentation for any unrecognized or erroneous command line arguments (unless that's so lengthy they need to only print a subset).

Re:A common language

[Anonymous Coward]

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.

Back in my day...

[Anonymous Coward]

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 selling

[istartedi]

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.

Re:There's also something to be said for selling

[Anonymous Coward]

They gushed because it was FRIGGIN AWESOME! You remembered because it made sense.

Wikis are not magical, but they are not bad

[gregmac]

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.

Re:Wikis are not magical, but they are not bad

[Zontar The Mindless]

With regard to technical documentation, wikis are where knowledge goes to die a horrible and lingering death.

Re:Wikis are not magical, but they are not bad

[redlemming]

I have never seen a program for which a wiki-based approach to documentation added any value. Can you give an example, please?

Re:Source code

[Anonymous Coward]

You can't have -help using getopt(3) or getopt_long(3), but it will usually resolve like -h anyhow, assuming you exit after printing the usage. If getopt_long is available I also always add --help. -? is a freebie, because you can aggregate -h and unknown options in the same block. Although, my code will send -h to stdout and exit with 0, but -? to stderr and exit with EXIT_FAILURE.

A / switch is not something you'll find in Unix land.

At the very least, all applications should provide -h, period. It's almost universally supported by system utilities.

Not all wikis are Wikipedia

[Idarubicin]

Reading the linked article, it is clear that this blogger is conflating two concepts: "wiki" and "let's leave a big blank space on the open interweb and hope that the magical crowdsourcing fairies will deliver us brilliant and complete documentation!"

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.

I too love reading great documentation

[gargleblast]

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 !!!

Re:I too love reading great documentation

[LinuxIsGarbage]

I too like good documentation. I only dabble in programming, but when the language reference explains all options, complete with functional examples, it's good.

Where I work (manufacturing process automation maintenance) I like being able to take a complex problem that no one understands, figure it out, and document it so those after me can understand it.

what separates good documentation from bad?

[csumpi]

up-to-date-ness

BD, DT, and wrote TFMs it'snot rocket surgery

[Tsu Dho Nimh]

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.

========
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 ... chronologically, what touches it and what is supposed to happen?

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.

Re:BD, DT, and wrote TFMs it'snot rocket surgery

[LinuxIsGarbage]

Start with things the way they should work, then give them some basic troubleshooting, maintenance, etc. for the added functions.

Oh basic troubleshooting. I laugh sometimes at how basic some of the basic troubleshooting is "Problem: Display won't light up. Possible problem: No power supply Solution: Check power supply"

I find it even funnier calling tech support, for companies that we pay a lot for tech support contracts, only to have them read back the same page of the manual I'm looking at word for word.

Re:BD, DT, and wrote TFMs it'snot rocket surgery

[Anonymous Coward]

This race hauling hogs up Pikes Peak sounds exciting, where can I sign up.

Re:BD, DT, and wrote TFMs it'snot rocket surgery

[Tsu Dho Nimh]

At the base of Pike's Peak, 6th Thursday in November. Drive the vehicle of your choice. Hogs will be provided.

First person to haul an aggregate weight of 1250K in hogs to the top wins. There is no limit on the number of trips, but all hogs must arrive at the toip for the vet inspection in good health.

Most FOSS documentation is abysmal

[hduff]

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'.

Re:Most FOSS documentation is abysmal

[Anonymous Coward]

That's how I got my entree into writing about Linux.

Your food writes about Linux?

Re:Um, yes

[real-modo]

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.

Documentation? Really?

[rueger]

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?

An excellent post, with one omission: pictures.

[QilessQi]

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.

Re:An excellent post, with one omission: pictures.

[rallytales]

Amen to that - the right picture truly is worth a thousand words. One or two good diagrams and a couple of paragraphs / bullet lists can convey more information, more effectively than pages of text. Sadly, I cannot agree with you on the quality of the post itself. Any useful information was buried in waffling pseudo-drama. I gave up reading after a couple of "acts". Rather ironic given the topic.

Re:An excellent post, with one omission: pictures.

[QilessQi]

I somewhat concur. Although I have a bias for illustrative stories, there is a time for entertaining metaphors and a time to impart information. Setting the stories off from the main text visually (as callouts or similar) would have helped us skip past them.

Re:Source code

[LinuxIsGarbage]

And for no arguments. Or at least print what is required to get help

C:\>app
Crappy app 0.0.0.1a
GPL 2 (If you don't like it fix it yourself

For help type -?

C:\>app /?
Crappy app 0.0.0.1a
GPL 2 (If you don't like it fix it yourself

I said enter -?, not /? This program was barely ported using cygwin, so you have to use *NIX arguments
Don't like it, fix it yourself
C:\>_

Re:Source code

[Anonymous Coward]

Nah,

The the thing is that most people are not programmers. Telling them to look at Wiki's, Source Code, or mile long README types of docs, are useless. These sources are for other developers who want to improve or make the application part of their workflow.

Those who wish to learn the software and are not programmers will simply be lost. I see this all the time with wordpress. People install the minimum required to get Wordpress running, and then get charged up the wazoo by their host because they don't install any caching or anti-spam plugins, so their disk space and bandwidth is chewed up in a manner of minutes instead of weeks.

Wordpress is a great example of doing everything wrong. It doesn't come, out-of-the-box in with appropriate plugins and is insecure by default. The average person running wordpress will have their site "hacked" at least once a year by defects in wordpress, without taking into consideration any plugins.

Non-programmers can not fix most OOP programs, even if they have the source code, because OOP programming is not for beginners. Non-programmers can usually fix a trivial 10 line javascript, not a 50,000 line Jquery widget.

Re:Source code

[forkazoo]

More importantly. The source code of a library isn't necessarily any use for understanding best practices for using a library. Reading libavcodec would be gloriously unhelpful for adding video support to an application.

Re:Source code

[interval1066]

use fewer source files, fewer classes, etc.

Hardly useful; I use as many or as few source files as I require, no more, no less. I make a conscience effort to make the number of source files fewer, but that hardly matters if your user-facing interface or API is easy to use. If its documented well, there's hardly more you can do I think.

Not documenting is a conscious technique

[WOOFYGOOFY]

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.

Re:Not documenting is a conscious technique

[Anonymous Coward]

There are developers with good documentation skills, but most suck at writing user friendly documentation. It is a skill one acquires after many years of practice.

There are projects that purposely have shitty docs to drive consulting, but most suck because they lack the skill. Writing great documentation takes a lot of skill.

Re:Not documenting is a conscious technique

[Anonymous Coward]

If software developers wrote a nice book explaining how their source code works... who would they sell it to?

So now they've spent several months writing a book, when they could've spent the same time on writing code that people would pay them $200 an hour to do. If the book is going to be any good, then the economics rapidly go even further south: there have to be reviews, revisions, more reviews and a detailed maintenance plan. When the dust settles, they're probably going to need several whole new full-time employees just to maintain this book - about one per 30-40 actual coders.

It's not that the book would destroy their market. (Who the hell would read it anyway?) It's the opportunity cost of writing it, which could easily run into millions of dollars.

Re:Not documenting is a conscious technique

[gnasher719]

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.

Is that why the openssl documentation stinks?

I tell you how bad it is. There's a method to get a string for the subject common name from a certificate. The documentation says it gives you characters and number of characters. It conveniently doesn't tell you that the data could be in any number of different formats, and there is no way to find out which format from the results of the function call.

It takes long hunting down in the code to find a method that returns the same data in Utf-8 format. How well is that documented? So badly that _both_ calls to the function from the openssl source code itself contain bugs.

Re:Not documenting is a conscious technique

[Anonymous Coward]

Basically true... to an extent. A competent boss will fire you for guarding your secrets, and as a developer, my advice is to do exactly that. Also, I don't guard my secrets because (a) I feel better this way, (b) it would contradict my own advice, and (c) I can only offload work to others if they are able to do it :D

That implies that I'm giving up a position of power... but sometimes the gain is worth the cost. But I also have to say that it depends a LOT on the way your company runs, and in a Dilbert-style company I'd probably act like you say (or get the hell out of there).

Re:Not documenting is a conscious technique

[WOOFYGOOFY]

It's a thoughtful point you're presenting but I have to counter. The value of writing the book is not to be found in the (opportunity) cost of writing it, it's to be found in

the many multiples of time units saved across very many people across a wide expanse of time who aren't , in isolation and individually (re-)wasting time to try to decipher WTF is going on in the code.

the time saved by the original developer because bug fixes are something more people can do.

the time saved by the original developer because feature adds is something anyone can do.

the innovation which takes place because writing something fundamentally novel which integrates with the existing code base is now a thinkable proposition to a large number of interested people.

the expansion of the market into areas which would otherwise be too costly and time consuming to enter into by experts who want that expansion to happen and have the motivation and knowledge to make it happen.

In my admittedly radical opinion, there is no such thing as "time wasted over-documenting" for an open source project.

I know large companies which appear to ostensibly have this attitude, but the people n(or usually person) *in charge* of documenting is the *WRONG* perons for the job. Typically, a dev who has an attitude that his (it's always a guy....) documentation *should be* (that part just kills me) good enough for anyone intelligent enough to be concerned about and supported. You have to love documentation and have a passion and empathy for people, a strong desire to succeed in rendering down highly technical information so even a high-schooler could catch on and a willingness to accept that the definition of being effective is measured by your customer, not yourself.

In this context, let me give a shout out to one Lisa Friendly, wherever she may now be, who was the editor in charge and also chief author of the Java Tutorials when Java was owned by Sun Microsystems. There was a person who,demonstrably had all those qualities in super abundance.

Arguably, Gosling made the language ,and she made it a success.

Re:Source code

[lgw]

Hahaha! Awesome.

) ) there, that's better.

Re:Source code

[Anonymous Coward]

Just for you, I name my methods things like bob, Bob, bOb, boB, BOb, BoB, bOB, BOB, _bob, etc. My text documentation is absolutely beautiful, though.

Re:His advice for wikis is what I've saying for ye

[Anonymous Coward]

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.

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.)

Re:Source code

[youngatheart]

Oh cool! I known that shutdown -r -t 600 works on Windows when I expect it to finish installing an update and I'm ready to go for a coffee, but I never remember what it is in Linux. Thanks to your tip, I now know I can use shutdown -h but I know the Linux guy had to put a number, so let me try shutdown -h 0 and see what it tells me about how

bah

[Charliemopps]

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.

Re:bah

[Zontar The Mindless]

Is your name really "Charlie Mopps"? And do you really believe you're doing it right?

You are a process junkie pretending to be a tech writer, and I want to be sure to add you to our "Do not hire even if Hell really is freezing over" list.

If your company has the resources to waste all that time and effort on something as inefficient as wiki--no, they don't. They are kidding themselves.

Re:Source code

[Anonymous Coward]

I try to use exactly one source file per abstract role. For example, I'll put an entire JSON, DNS, or HTTP library in a single source file (this is all C code, mind you), because it makes it infinitely easier to reuse the code without resorting to a full-blown shared library. It also allows me to tweak and experiment on a project-by-project basis, without worrying that a single change will break some other application, but when I do migrate changes over it's as simple as a copying a single file (or two, with the header).

I see too many projects which break down something simple into half a dozen source files.

Some of my projects may have twenty or thirty source files. Putting an entire JSON parser/composer in a single source file seems stupid until you see it embedded inside a larger application. Then it makes a ridiculous amount of sense. How does this app handle HTTP? Oh, it's in http.c. How does this application handle daemon startup and option processing? Oh, it's _all_ inside main.c, carefully layered out in layers from top-to-bottom.

The problem is that people write their projects as-if they're the only project in the universe. Especially neophyte programmers, who dream about creating the next greatest module system, etc.

I think this is why functional programmers do so well. Because of the nature of purely functional programming, you have to think long and hard about the simplest interface to your module. You can't simply offload the work by requiring the user to juggle or protect a ton of state.

In OOP-land, I think this is why people who suggest to avoid subclassing are correct. If you're implementing a Zebra, implement the platonic ideal of a Zebra, not a horse subclassed with stripes. 9 times out of 10 that additional abstraction will go entirely unused except by your Zebra, and the conciseness of the Zebra implementation will suffer.

Re:Source code

[VortexCortex]

-h? Next time, use all three of these: -?, -help, --help. I'm probably not going to try throwing -h at a program without having a clue what it might do.

Then use the damn manual. That's why we write them. If you want to know how to use the manual, use the manual:
$ man man

... hmm, That gives me an idea.
$ man woman
No manual entry for woman

Yep. It knows everything!

Not just computer science

[recrudescence]

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!

Re:Not just computer science

[sandbagger]

Well, actually that's a very good question to start a course. If the instructor doesn't know your level of knowledge is, is just plain common sense.

Who is the arrogant prick again?

Re:Not just computer science

[recrudescence]

I disagree. You can gauge your interns' level of knowledge *while* having a lesson plan, and an insight on why it merits teaching in the first place; just showing up for a hard-arranged tutorial completely unprepared and willing to just 'wing it' because you totally think you know your stuff and can't be bothered to prepare a structure, let alone a topic, just doesn't cut it.
If you *really* want to ensure you don't tread on previously covered ground, you prepare a couple of topics, and allow the students to choose. You don't just show up with coffee.

Also, seriously, there was no *actual* need for the smug retort at the end there really, was there? What are we, twelve?

In all seriousness, there's an epidemic of clinicians who haven't done a day's worth of formal teaching-skills education in their lives, who suck in teaching as a result, but think they're hot stuff because they know their medicine well. And when the clinician is unable to transmit his ideas, the students / interns get blamed instead. To bring it back to the original article, it's worse than "just read the code", it's more like "just read the code that's in my head".

manor? Please define your terms upfront.

[Anonymous Coward]

manor? Please define your terms upfront.

Nobody here is concerned with discussions held on small English estates.

Re:Source code

[sydneyfong]

In some languages the getopt() equivalent is pretty readable.

It's sort of unfortunate that after so many years, plain C is still the de facto standard language for Unix-alike systems. The limitations of the language (that it is designed with machine implementations in mind, instead of with human readability) makes it necessary to document more things than otherwise would have been in an ideal (/perfect) world.

Re:Source code

[Anonymous Coward]

You are an idiot.

Re:Source code

[Aaron B Lingwood]

-h? Next time, use all three of these: -?, -help, --help. I'm probably not going to try throwing -h at a program without having a clue what it might do.

For non-Windows systems:
-h is Valid
-? is Invalid as '?' is a special parameter that may be expanded by the shell
-help is Invalid on GNU/Linux (though used often by ported applications)
--help is Invalid on older Unix systems.

For newer Windows systems:
-? is Valid (and mandatory)
-Help is Valid (and mandatory)
--help is Invalid
-help is Valid
-h is Valid

-h is the safest option

Re:Source code

[Gorobei]

Wow. That was the most common sense thing I've read in a while. Want a job in NYC?

There are two problems with documentation...

[brantondaveperson]

1) Nobody writes it.

2) Nobody reads it.

Re:There are two problems with documentation...

[dfsmith]

TL;DR

Great in theory, but what about cost and bit rot?

[J Story]

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.

I tried the teach don't tell method at my current

[pecosdave]

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".

Always odd

[sugarmotor]

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

Re:Source code

[noh8rz10]

reminds me, I hate man pages. there, I said it. they are the devil. i have never learned anything important from a man. rftm, you say? well stfu!

Re:A common language

[Anonymous Coward]

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

[swell]

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.

Re:Um, no to no

[Anonymous Coward]

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.

writing docs

[l3v1]

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.

see, this is what I'm saying...

[globaljustin]

Who cares about non-techies? we're talking about API docs

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

Re:see, this is what I'm saying...

[spottedkangaroo]

We're talking specifically about the point that there's a difference between API documentation (which should be an exaustive list of every function and the arguments it takes and why) and a tutorial that talks about how to use the thing. You're likely to find both in The Docs or they're simply not complete. And the point I was making was only that a techy will point out the difference or someone learning to program will quickly find the difference and then look for the tutorial first and the docs later when they're further along. That is the only point that I was making.

Everything else is a silly pointless argument. But this is the main takeaway: The Docs are almost always incomplete because there's nobody that's volunteered to write them and nobody paid to write them. What are you going to do? force the guy that volunteered to write the code to volunteer to write the docs? I doubt it's going to happen, so you'll have to live with reading source, writing your own, or using something else. If you lucked out and the dev wrote little blurbs above the function, great. If someone put some examples in a wiki, even better. If someone just happened to write geniuous docs, well, you've really found a gem and you're going to find a mix of tutorials and API docs and tutorials/examles for the good ones. The API docs are more important thouguh, cuz if all you have is some examples, you're going to go source diving without the API docs or you'll have to find something else.

Re:Um, yes

[Anonymous Coward]

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!"

Re:A common language

[Anonymous Coward]

Seems like a nerve has been hit.

Re:Great in theory, but what about cost and bit ro

[gnasher719]

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.

No one should document their own work!

[dryo]

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.

Re:Source code

[Bongo]

Speaking as someone who studied architecture (bricks, not computers) I see similarities. The first rule of design was that you only learn the real problem by trying to solve it. Then when you realise why your first attempts are so horribly broken, you can use that understanding of the problem to actually start a design that works. But it is as much top down as it is bottom up, so you need both a clear simple overall architecture, but without it compromising the space to work out the details properly. So it is very iterative, some important details and constraints may break your elegant framework. The iteration usually stops not when it is finished but when you run out of time.

The notion of "site" is also very important, as every site is different and so every building is effectively a prototype, a design of one. This affects all sorts of subtleties in the project, so abstraction is nice for trying to think more quickly and simply, abstraction doesn't in itself solve anything, because the devil is always in the details. The details can't be hidden by abstraction, but they can be organised by abstraction.

Executive Summary

[martin-boundary]

(for those still learning to read)

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!

Misguided rants

[Jonner]

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.

Re:Source code

[smash]

Given the number of bugs in most code, I'd suggest that it is pretty poor documentation for what the code is SUPPOSED to do.

Re:Source code

[1s44c]

You what? Man pages may not easily teach you how to use the tool but they are an excellent reference once you have some clue.

What do you do to get information about the tools on your system? Google everything and get the answers for some other version of the same tool?

This article is bullshit

[Anonymous Coward]

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.

Put your reading glasses back on

[davide marney]

He didn't say "experts need to be taught", he said, "teach someone to become an expert." Big difference.

Re:Source code

[noh8rz10]

if a person doesn't know what grep is, will he learn the tool through man grep? he'll learn the vsrious switches, but he won't understand teh concepts behind the tool and won't be able to apply it effectively. what's the good in that? I say, ask google using a natural language search, and see what you get. actually, ask siri, i bet she'd call up the relevant wiki or wolfram page.

Re:Source code

[Anonymous Coward]

Worse, it's one for ssh, another for scp. Rsync is a separate project so you can expect the options to be different.

Re:Source code

[Qzukk]

"Every utility I write has an -h switch, which describes the switches option-by-option, followed by short description of the function of the utility, plus gives links to additional documentation."

That's nice. If I ever get attacked by a switch in the wild i'll know I can use -h to tell me what that switch is.

Now that I know what every switch is, tell me how to use them to achieve my goals.

That's what really makes the difference between being a reference and being instructions.

Re:Source code

[SleazyRidr]

Haven't used MS-DOS since 1990. No one cares. Joke is still funny.

Re:Source code

[Anonymous Coward]

I said enter -?, not /? This program was barely ported using cygwin, so you have to use *NIX arguments
Don't like it, fix it yourself
C:\>_

I am SO going to include this in my code from now on.

For the Love of Mike: Add Dates AND VERSIONS!!!

[PurplePhase]

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

[Ash-Fox]

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.

documentation for open source developers

[hendrikboom]

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

Read the code doesn't do it...

[whitroth]

... 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

for sure...

[globaljustin]

having a "here's how to do the most common thing" tutorial ... is probably sane

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!

Re:Source code

[Entropius]

Grep is a special case because regexes are complicated. But a tool like ls? Read the manpage.

Re:Source code

[LinuxIsGarbage]

Using msdos since 1990, /slash switches are overall less common on msdos and its children than -minus switches were.

Nevermind that / is a poor choice due to its meaning as a directory separator. (Yes, windows supports / as dir separator for the last ten years or more).

But please, parade your lack of familiarity with your platform more.

straight from my cmd window

You were saying?
Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. All rights reserved.

C:\>dir /?
Displays a list of files and subdirectories in a directory.

DIR [drive:][path][filename] [/A[[:]attributes]] [/B] [/C] [/D] [/L] [/N]
[/O[[:]sortorder]] [/P] [/Q] [/R] [/S] [/T[[:]timefield]] [/W] [/X] [/4]

[drive:][path][filename]
Specifies drive, directory, and/or files to list. /A Displays files with specified attributes.
attributes D Directories R Read-only files
H Hidden files A Files ready for archiving
S System files I Not content indexed files
L Reparse Points - Prefix meaning not /B Uses bare format (no heading information or summary). /C Display the thousand separator in file sizes. This is the
default. Use /-C to disable display of separator. /D Same as wide but files are list sorted by column. /L Uses lowercase. /N New long list format where filenames are on the far right. /O List by files in sorted order.
sortorder N By name (alphabetic) S By size (smallest first)
E By extension (alphabetic) D By date/time (oldest first)
G Group directories first - Prefix to reverse order /P Pauses after each screenful of information. /Q Display the owner of the file. /R Display alternate data streams of the file. /S Displays files in specified directory and all subdirectories. /T Controls which time field displayed or used for sorting
timefield C Creation
A Last Access
W Last Written /W Uses wide list format. /X This displays the short names generated for non-8dot3 file
names. The format is that of /N with the short name inserted
before the long name. If no short name is present, blanks are
displayed in its place. /4 Displays four-digit years

Re:Source code

[Anonymous Coward]

Why do you claim --help is invalid on Windows?

I'll trust you that --help is not valid on old Unix system (I assume some programs might interpret that as five options), but to say it's invalid on Windows is just silly.

I've used (and written) a number of tools that respect --help, and it needs no special handling from the system. Offering multiple methods is of course the best policy, because everyone tries something different first.

Re:Source code

[Aaron B Lingwood]

Why do you claim --help is invalid on Windows?

It will work (at the moment) but goes against the conventions set by Microsoft.

Microsoft could, at any time, change the way it interprets a double hyphen, breaking your program.

It is safe at the moment because Windows passes the entire parameter string via ARGV

Re:Um, yes

[real-modo]

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.

Re:Source code

[bbsalem]

Wow, that is a great non sequitor, the part about having common sense and then taking a job in NYC :-)

Is Poor Documentation a way to limit competition?

[bbsalem]

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.

Re:Source code

[Anonymous Coward]

That's even more stupid - any author of any system could at any time change the rules and break existing programs. In fact, Unix is more prone to this than Windows, going by your earlier statement.

There's no guarantee Microsoft won't decide to break programs using their established conventions too - except that it would be bloody stupid to do so. Not to mention that even their own "conventions" vary significantly from tool to tool.

I don't think I'm going to worry about the possibility that Microsoft might stop passing command line options to programs. It's a ridiculous fear, and the fact that you got even one mod point for this shows how far Slashdot has fallen.

Re:Source code

[Aaron B Lingwood]

That's even more stupid - any author of any system could at any time change the rules and break existing programs. In fact, Unix is more prone to this than Windows, going by your earlier statement.

My post is not about changing existing rules, but leaving room to add more features. A single hyphen is to be used for command line arguments. This leaves a double hyphen available for a future use; whether that be implementing GNU-like syntax, some new security paradigm, a switch to set a flag, or any number of uses.

There's no guarantee Microsoft won't decide to break programs using their established conventions too - except that it would be bloody stupid to do so. Not to mention that even their own "conventions" vary significantly from tool to tool.

Standards, conventions, guidelines, and rules are all there for a reason. It is one method of future proofing and is vital to follow for a program to exhibit expected behaviour. Why be a maverick and use double hyphen when there is no need whatsoever other than to be different. That is hipster-coding.

I don't think I'm going to worry about the possibility that Microsoft might stop passing command line options to programs. It's a ridiculous fear, and the fact that you got even one mod point for this shows how far Slashdot has fallen.

Microsoft won't stop passing command line options to programs - that would break every program. What Microsoft MIGHT do, and it would be both safe and fair for them to do so, is have the shell examine the parameter string, cut out double hyphen parameters, pass the remaining string to ARGV, then act on those cut parameters separately prior to or simultaneously with program execution. If developers have acted competently and followed the conventions, this will not cause any issues.

This is not a fear - it is just common sense. I got a single +1 Informative as someone has either learned something, has thought about something they haven't put their mind to before, or thinks that someone else may benefit from the information. I am not a developer. I am not a Windows user. But I read, and I absorb. It is called listening. That more people don't do it shows how far society has fallen.

Re:Source code

[Anonymous Coward]

What Microsoft MIGHT do, and it would be both safe and fair for them to do so, is have the shell examine the parameter string, cut out double hyphen parameters, pass the remaining string to ARGV

No, that would not be safe and fair for them to do. For starters, it's perfectly valid for a filename to start with two dashes.

Re:Source code

[Aaron B Lingwood]

it's perfectly valid for a filename to start with two dashes.

It is also perfectly valid for a filename to start with a single dash. But that is irrelevant to the issue.

The issue is with the parameters / command line options / arguments. This is the part AFTER the program name. $args contains an array of everything after the filename, delimited by breaking space (and a few other scenarios). Single hyphen parameters within these arguments can be automatically parsed and set. Double hyphen parameters are not a documented feature, are unsupported, and may exhibit behaviour that the user does not expect.

The term 'Best Practice' exists for a reason.

Re:Source code

[Anonymous Coward]

Single hyphen parameters within these arguments can be automatically parsed and set. Double hyphen parameters are not a documented feature, are unsupported, and may exhibit behaviour that the user does not expect.

You already stated you're not a programmer, and I think I see the confusion. You seem to believe there's something automatic about parameters, and that the system does some processing for you.

This is not the case, on Unix or Windows systems. Libraries exist to do things like this (e.g. getopt), but there are numerous libraries and they all do things differently, and each program has to set up and initiate whatever parsing it wants to do.

There is no standard, though Posix includes recommendations (and GNU recommends an extension beyond this). The only exception might be Powershell, which tries to standardize on single-dash-long-name options, with shortcuts for common parameters.

Of course, it's also possible you're just trolling...

Re:Source code

[Anonymous Coward]

I hate you! You're one of those co-workers that urgently e-mails me at 1AM in the morning asking me how to use some utility I wrote. In the morning I reply, "Use the -h switch, you mother f*cker." Followed by my usual disclaimer--"Every utility I write has an -h switch, which describes the switches option-by-option, followed by short description of the function of the utility, plus gives links to additional documentation."

Uhm... what? How did you come to that conclusion?? You are creating some imaginary enemy here, probably because of your frustrations at work from working with lazy people.

I said source code is by definition guaranteed to be the most up-to-date explanation of how things work. Your command line options are in your source code. Your wiki can be out of date, your Word spec in a shared folder can be out of date, but your source code off of which you build & release will be the place where I will find accurate answers to my questions, guaranteed.