Writing Documentation: Teach, Don't Tell 211
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."
Docs vs tutorial (Score:2)
'help' (Score:4, Interesting)
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: (Score:2)
Re: (Score:2)
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 w
see, this is what I'm saying... (Score:2)
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
Re: (Score:3)
Petzold, Prosise. Two examples of good documentation. K&R, a different approach.
Wrox, how not to do it.
Go forth and multiply.
Re: (Score:3)
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 integr
Re: (Score:2)
Re:Docs vs tutorial (Score:5, Insightful)
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: (Score:2)
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: (Score:2)
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 (Score:5, Insightful)
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: (Score:2)
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 anyon
Re: (Score:2)
See, if this was a wiki I could go back and edit out that annoying apostrophe that sneaked into my second sentence.
Wikis are better than nothing (Score:2)
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 langu
Stack Overflow (Score:4, Informative)
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: (Score:3)
Re:Stack Overflow (Score:5, Informative)
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: (Score:3)
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 (Score:5, Insightful)
Re: (Score:2)
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: (Score:3, Insightful)
Same thing happens here. This is how your previous post got modded up.
Re:Stack Overflow (Score:4, Insightful)
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: (Score:2)
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 (Score:4, Insightful)
Re: (Score:3)
"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: (Score:2)
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 qu
Re: (Score:2)
Re: (Score:2)
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: (Score:2)
"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?
Um, no (Score:3, Insightful)
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: (Score:2)
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
Re: (Score:2)
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 (Score:5, Insightful)
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: (Score:3)
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 wi
Re: (Score:3)
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: (Score:2)
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: (Score:2)
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 fil
Re: (Score:3)
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.
In other words... (Score:2, Redundant)
...the author doesn't understand what documentation is supposed to be used for.
The web and hyper text are a challenge (Score:5, Insightful)
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: (Score:2)
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: (Score:3)
Re: (Score:3)
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.
Havi
blurred lines (Score:2)
I like seeing this alot:
That's it in a thesis statement.
What does 'documentation' or a 'user manual' that **teaches** not dumps random data actually look like???
Complexity is the problem, and it causes blurred lines in areas that in a simpler technical area (with less uncertainty), say auto repair, would not be uncertain.
Computer programs, languages, API's, etc are insanely complex compared to a radio
A common language (Score:4, Insightful)
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.
Re: (Score:3)
peaked before the new developerl.
Freudian slip much?
Worst car analogy ever (Score:2)
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.
truer words have never been written (Score:2)
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
There's also something to be said for selling (Score:3)
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.
Wikis are not magical, but they are not bad (Score:2)
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 docum
Re:Wikis are not magical, but they are not bad (Score:4, Insightful)
With regard to technical documentation, wikis are where knowledge goes to die a horrible and lingering death.
Not all wikis are Wikipedia (Score:3)
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 [wikipedia.org] 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 (Score:2)
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: (Score:2)
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? (Score:2)
BD, DT, and wrote TFMs it'snot rocket surgery (Score:3)
I've been writing technical documents since the early 1970s.
You can't expect one piece of documentation to serve everyone ... it's like buying a "vehicle" and trying to use it to race, haul hogs, and climb Pikes Peak.
A - Ordinary users don't give a shit how the stuff works, they want it to do something for them ... tell them how to make whatever it is work as a tool for them. Run through the common use cases, screen by screen, showing them how to make the widget-smasher do it's thing.
Start with things the way they should work, then give them some basic troubleshooting, maintenance, etc.
B - Administrative users: They need all of "A", and how to handle the other users. Add, remove and monitor users.
Start with things the way they should work, then give them some basic troubleshooting, maintenance, etc. for the added functions.
C- Service techs, sysadmins, and those who will touch the sacred code: All of A and B (be reference to the appropriat4e manual or section thereof) and then feel free to pile on the technocrapobabble.
Each detailed explanation should start with a very brief "statement of purpose" ... when will this command be needed, or what does the bit of machine do. Why would you use it?
Then explain how to use it, and the expected results if you used it right, the expected results if you screwed up, and how to recover from an error.
======== ... chronologically, what touches it and what is supposed to happen?
You need to explain for each level of user what happens to a transaction, or data, or a part being manufactured, as it passes through the process or the proigram
What will you see if there is a failure?
How do you recover from the failure?
It's not difficult, you just have to make sure that each level of user can get their task done efficiently.
Re: (Score:2)
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.
Most FOSS documentation is abysmal (Score:5, Interesting)
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'.
Documentation? Really? (Score:2)
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!
An excellent post, with one omission: pictures. (Score:5, Interesting)
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.
Not documenting is a conscious technique (Score:3)
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: (Score:2)
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 we
bah (Score:2)
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 the
Re: (Score:2)
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.
Not just computer science (Score:3)
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: (Score:2)
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?
Great in theory, but what about cost and bit rot? (Score:2)
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
Re: (Score:2)
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.
I tried the teach don't tell method at my current (Score:3)
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 (Score:2)
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
documentation is for people (Score:2)
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
writing docs (Score:2)
Most docs are written by people who didn't do it by choice, and it s
Executive Summary (Score:2)
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 gol
Misguided rants (Score:2)
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
Re:Source code (Score:5, Insightful)
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...)
Re: (Score:2)
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 (Score:5, Informative)
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.
Re:Source code (Score:4, Informative)
Re:Source code (Score:4, Informative)
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:Source code (Score:5, Funny)
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 (Score:5, Funny)
-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
$ man woman
No manual entry for woman
Yep. It knows everything!
Re:Source code (Score:4, Interesting)
-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: (Score:3)
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:Source code (Score:4, Funny)
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: (Score:2)
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?
Re: (Score:3)
Grep is a special case because regexes are complicated. But a tool like ls? Read the manpage.
Re: (Score:2)
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.
Re: (Score:3, Funny)
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
Re: (Score:2)
Wow. That was the most common sense thing I've read in a while. Want a job in NYC?
Re: (Score:2)
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
Re: (Score:3)
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 (Score:5, Insightful)
Re: (Score:2)
Maybe not the way you use it....
Re: (Score:2)
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 cli
Re: (Score:3)
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
Re: (Score:3)
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: (Score:3)
"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.
Re:Driver's Manual (Score:4, Insightful)
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: (Score:2)
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 ev