How do you decide what to write about? How do you organize what you’ve written? Often, your view will be shaped by the technology you’re used to. Mallard users will think of topics and guides. DITA users will turn to tasks and concepts. DocBook users will line up chapters and sections. All of these have their pros and cons, but there are three types of documents you need to stop writing.
README: Read you? I’ll read what I like, thankyouverymuch. What’s in this README file? Instructions for how to use the software? How to install it? Develop plugins for it? Start contributing to it? The answer to all of these is yes, and much more. I just don’t know what’s in there. All I know is that somebody thinks I should read it. Maybe.
TODO: I want to know what I can do with your software today, not tomorrow, and certainly not in your imagined tomorrow. By all means, keep a TODO list. Better yet, use an issue tracker. Software development is hard work, and we all need help keeping track of what we need to do. But don’t put it in your user documentation.
FAQ: I don’t care if my question is frequently asked. There are many ways you could organize information, but an FAQ isn’t a taxonomy. It’s a brain dump of answers to some questions somebody had. Worse, it’s often a brain dump of answers to questions the developers think you should ask. (Did anybody really ask how your project got its witty name?) Identify the valuable information in your FAQ and take the time to work it into the organizational structure of your documentation.
All of these are failures to identify the audience and organize information for them. A writer’s job doesn’t end with writing some words and just putting them somewhere. When writing and organizing, always think of where your reader is likely to look for the information you’re providing.
So, I have to disagree on the README and TODO. For *nix projects, these are expected pieces of documentation. If nothing else, the README and TODO should exist as pointers. README should give users tips on where to start if they’re getting your code as a tarball or a third-party source (e.g., as an installed package). The TODO can be nothing more than a pointer to your issue tracker’s wishlist items or something – but they should exist. FAQ… well, that could probably go.
I have a love-hate relationship with the standard autotools layout. I do see the utility in standard files to provide information, but I wish we’d move towards machine-readable files like the DOAP files in all GNOME repositories. But the README file has moved beyond that. Due to GitHub’s awesome ability to render any Markdown files in your repository, the GitHub generation is prone to writing a single README.md file and claiming they have good documentation. Usually, they don’t.
Just to make a point: I quite often care how things got their name. I distinctly remember looking up the history of names on Wikipedia. So there.
Let me save you the trouble:
1) It’s a portmanteau.
2) It’s an acronym, but the developers already had the name they wanted, so they made up something about network objects to make the acronym.
3) It is a similar thing to the name or iconography of another project. This happens most often with animals, like ducks and whales.
4) It’s the name of a person, group, or event with historical significance.
5) It’s a foreign word. For bonus points, combine (1) and make a portmanteau of foreign words. For extra super special bonus points, make a portmanteau of words from different languages, like Παν語.
I disagree with this post. These files are very relevant. If you’re not interested, fine, but many of us are. One type of documentation I would like to see more are man pages. Some new projects seem to think that man pages are passé and don’t provide them, which is a horrible thing to do in a *NIX ecossystem.
If I’m not interested in what? The title gives me no indication of what’s in the document. I have no idea what I’m missing by not reading it. Is it a cute story about how you came up with the project? Is it critical information that will help me prevent data loss or injury? I just don’t know until I read it.
One that makes even less sense: INSTALL. Please have installation documentation on how to set up your software, but when I see the first lines of the autotools default INSTALL file, I know I’m not getting any useful help.
I disagree. An INSTALL file is fantastic and it’s always a bit of a relief when I open one and see the standard autotools language. This says immediately that I am dealing with a known quantity, that I know how to install this software. It says “There is nothing new, quirky or special here. Your standard autotools knowledge is enough.” Wonderful news! I can begin building with confidence.
Provided, of course, that this turns out to be true.
What a funny post.
What are you talking about actually? User documentation?
READMEs and TODOs are developer documentation. README is the first place to look at, when you open a tarball. You don’t like the name? What an argument against its content (…). INSTALLs are developer documentation too. Autotools will create a default one, it IS very useful if you don’t know autotools. I think you failed to identify their audience.
About FAQs, your post just say “Don’t write bad FAQ” — that’s very good advice, thanks — exactly the same way we say “don’t write bad user manual”. A FAQ IS a very good user documentation for… tadam… frequently asked questions.
What I actually understand from your post:
– Don’t include README and TODO in user documentation,
they are developer documents
– Don’t write a FAQ if there are no frequently asked questions.
Even a good FAQ is, by its very nature, poorly organized. I said to take the time to work the information into the organizational structure of your documentation. Information on emulating a mouse with the keyboard could be grouped with keyboard information, mouse information, or accessibility topics. These are all sensible things that match what the reader is thinking when looking for information. The reader is not thinking “I’ll bet this question is asked frequently.”
README: general information, scope and limitations of the software without having to read all the code, usage, etc. (“This package uses the Bulirsch-Stoer integrator for this problem because…”) Useful stuff.
INSTALL: not everyone is well versed in installation process. Some customization flags may be possible, requisite/optional packages to install may be suggested. Lot’s of possibilities there. That’s the kind of things that helped me learning on how to use several different tools when I first switched to Linux, and keeps README cleaner.
TODO: what are the current plans for the project? I may follow it more closely with a good list of things planned for implementation or extension. It’s also useful to make sense of placeholders in the code, if I’m reading it. Maybe I can even offer collaboration if I find myself intrigued, interested and have the skills. This will likely be a file that will need changes more often, so it well deserves being apart.
FAQ: I would make that be a section of the README, if really needed. I have come across some exotic software that really need a FAQ, but they don’t always have one. It’s good for outsiders to the topics or their actual implementation, or as a response to requests on how to use with it that other project XYZ, etc.
If you consider an FAQ to be unstructured, you’re doing it wrong. A good FAQ is organised into logical sections and provides and easy way for common questions to be answered very efficiently. It’s not going to answer every question and that should not be the goal. If you follow the 80/20 rule you can filter out a large amount of repetitive questions on forums and to support without having to tell the user to RTFM.
You may not be the intended audience of these documents. Many projects provide these documents in their source code and someone outside the project packages and distributes them as “documentation” with little regard for the audience they are addressed to. *That* is likely the real problem.
These are traditional files in some software subcultures yet do not imply that it’s the only way the project’s information will be organized. Telling people to stop writing these is the same as telling them to stop serving these subcultures in favor of others. That’s seems like the opposite of what inclusive projects and communities would want to do.
I don’t believe many people spend alot of time honing their READMEs and FAQs. So even if you’re worried about how you think project contributors ought to spend their precious time chances they’re not “wasting” much of it.
Lastly, FAQs often have somewhat non-obvious uses when it comes to learning about a new project. FAQs can help me quickly get to the point that I can ask intelligent questions in a community that I’m unfamiliar with. It’s not terribly impressive if I ask a question that every new user/participant asks and which has been asked many times before. Furthermore, the questions themselves can very quickly introduce me to ideas, problems, and solutions I had not considered. Often these can save me a great deal of time and frustration later.
That said, *some* FAQs are enormous because they attempt to answer all possible questions. The answers could be lengthy because they attempt to supply all possible ways of expressing the answers. These are poorly written FAQs but they are not a reason to avoid writing FAQs altogether.
README should contain the same information as main page or ‘About’ page of project homepage, namely what it is for.
Hi there!
This is actually regarding Passive Voice Day – Just wanted to let you know a bunch of people celebrated it: https://www.facebook.com/photo.php?fbid=292210467530433&set=a.269651129786367.65753.269642853120528&type=1&theater