WTFM - Write The Freaking Manual
floopsy.com
floopsy.com
But it seems like there's a big trend now to just "get things out there" and that good documentation isn't "cool" anymore, kind of like braces in syntax.
Examples of good docs: PHP, jQuery, MySQL. (The first two sites include user comments too, which make things even more useful.)
Examples of terrible docs: Python, CoffeeScript (the worst)
I can at least understand insufficient docs for pre-1.0 versions when the implementation is changing constantly, but when something has been around for more than a year, it's just inexcusable.
I don't want a "getting started" guide that gives a bunch of examples. I don't want to type in the console to find out what methods an object has.
I want a friggin' reference manual, that includes (as applicable) syntax rules, exact rules governing whitespace, orders of operations, all functions, all parameters, parameters passed to a callback (why are these forgotten so often?), default values, flag values, all possible return values, specific exceptions that can be thrown, what input parameters result in undefined behavior.
Really, it's just not that hard. It may be grunt work, but if you'd rather make your users waste a cumulative 25,000+ hours figuring things out, rather than you spending 100 hours of your own explaining things, I just can't have respect for your product, no matter how otherwise amazing it is.
1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)
2. Whitespace (section 2.1)
3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)
4. All functions, types, classes... both globals and stdlib modules are documented in http://docs.python.org/library/index.html#library-index
5. All parameters? Documentation should already have these.
6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented
7. Default values and their meanings are pretty much always documented
8. I don't know what flag values are, but if they're just parameters they fall under (5)
9. Return values and exceptions should always be documented
10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.
A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed.
So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python libraries. There didn't appear to be the equivalent of RubyGems or Bundler. There did seem to be 2-3 different ways of managing them (eggs?), but just getting those programs working on my local system wasn't liking me either. Googling for "Using Python libraries" didn't return much useful- nor did "Installing Python Libraries".
I'm still unclear what the standard method for managing these is. When I checkout a Ruby thing, I just type 'bundle install' and all is fine then.
Yes, the technical docs were fine- but the baseline "how do I get this damn stuff, working!?!?!" wasn't.
If only this was just a documentation issue. Alas, the reason is that there is no standard method. Here's a short practical article on how to install Python packages and get on with your life: http://dubroy.com/blog/so-you-want-to-install-a-python-packa.... For a longer historical perspective of this whole clusterfuck check out http://lucumr.pocoo.org/2012/6/22/hate-hate-hate-everywhere/
1: http://pypi.python.org/pypi
Edit: There's also the official documentation page called "Installing Python Modules" which covers the last of those three methods: http://docs.python.org/install/index.html
Edit 2: and from the FAQs, http://docs.python.org/faq/library.html#general-library-ques...
For now, you can get most of the way by trying 'pip install X' or 'easy_install X', but there are important edge cases.
It's being worked on for Python 3's next big release, last I heard.
If you ask me to do the same in Ruby, I'd probably be lost too.
Most of the times I'm looking at CoffeeScript to just figure out what it compiles to!
There's a critical gap between the expectations of Ruby/Java programmers of how to write Python and the way Python programmers behave. I think it really is cultural, to an extent. The Java programmers look for Java-style documentation, with classes and methods and lists of exceptional conditions. The Ruby programmers look for Ruby-style documentation, with lots of diversions into the "why" of things and the context, possibly with pictures of foxes.
A Python programmer would consider the Java docs needlessly detailed and the Ruby docs a bit fluffy and not to the point, but after all, it is just a matter of viewpoint, community goals, and culture. There's also the issue of installing packages in Python, which can be a bit of a bummer, but I've never had a problem downloading a Python package from some site and following the directions.
Reference manuals are still nice to have of course for clarifying edge cases and solving language lawyer disputes. However claiming that they are a superior learning and time-saving tool than the learn-by-example techniques is way out of touch with how most people actually learn.
If you are only doing your own product using Python libraries, then certainly you don't.
The times when I've actually ended up writing some docs, I don't think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all.
I don't read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it's never out of date and tells the whole story. What was obvious to writer of the doc isn't obvious to me and vice versa.
The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.
You are selling yourself short. Your documentation the first thing people see. If it says "incomplete, confusing, and half-hearted", I'm going to hit the back button in about 15 seconds. I'm not going to spend 15 minutes reading your code to see if the first impression is wrong unless I think there's no viable alternative project.
Conversely, if your documentation is clear, thorough, and gives examples of usage, I'm likely to trust your project and dig deeper.
It's even been argued that writing the docs first helps you develop better: http://tom.preston-werner.com/2010/08/23/readme-driven-devel...
It's useful for keeping your code in conformance with documentation. The problem is when the original spec turns out to be impossible (or difficult/expensive) to implement, and needs to be changed.
However if you doc then build, you've got a change control process that should accommodate this.
The only way you can figure out if these releases do what you want is to spend half an hour trawling through the source code. Over the years I must have wasted weeks of productive time doing just that, and I can't believe I'm the only person who has.
I don't expect full API documentation and set of unit tests for every open source project - I'd be happy if most projects came with a short overview of how the code works, how it is implemented, maybe a couple of examples, and a list of its limitations. I do that for most projects I write for myself, to make it easier to come back to in a year or two when I next need to work on it.
If your project isn't worth spending an hour writing some basic documentation, then it isn't worth releasing.
Sorry, if you don't have documentation, even a little bit, you're just not worth my time. There are at least two other libraries out there with better documentation. The fact they might be worse software doesn't even matter because all I'm looking for is a solution.
Further, demands for great documentation are unreasonable. I can point to hundreds of examples of 'well documented' projects where I still dig into the source code and do simple experiments to learn what the heck it does. This is a combination of how I learn and how I use software. Your docs (for all values of you) are crappy and don't tell me how the software works - the code does that tho, so I actually can trust it. If you want to do truely great documentation, put some comments of expected use at the top of the function/class/whatever definition, some comments on tricky sections of code (not "this does the file read" i get that from the call to read(), but "this also triggers an event from the OS handled in foohandler()), and good clean loosely coupled components.
Good documentation provides context and use cases. Good comments in source code provide clarity as to what the code is doing. They are in no way equivalent.
One of the benefits of encapsulation in software is that it enables individuals to program against a documented interface without spending (although in many cases I'd say wasting) time to understand the intricacies of implementation. You lose that benefit if you're forced to dip into code to understand how to use that code.
You do have a point, though - as an open source dev, it's your time to spend as you see fit. But a quality open-source project is more than the sum of its code.
I agree with both of you - I don't see software as "complete" unless it has documentation, it's part of the package to me. I happen to like writing it, but I hate some other aspects of programming - doesn't mean I skip those sections.
However, I have put things online without documentation before, because the software wasn't complete but maybe someone else would complete it, or find it useful, or learn something from it. Maybe they won't - but I lose nothing by putting it online, and the world stands to gain.
The worst thing that could happen is that someone would want to start using your library while it's in an alpha state, and then complain that it's not perfect. But in the end, if people would really find something you're working on useful, you might get a lot of community support and motivation to finish it, so why not?
And as you state, when features are completed, there should be pages with ample examples on how to use them. Programmers can usually read a code example ten to a hundred times faster than they can read over the documentation for everything used in that example, and in well written code, the expected functionality (that is: documented behavior) is clear from an example alone. Programmers can also write a quick code example with a few inline comments faster and better than they can write good documentation.
Projects which are an early stage (like most of my projects) should mostly try to attract potential contributors, not just consumers/end-users so it's not unreasonable to require would-be users/contributors to walk the extra mile and actually read (at least parts of) the source. I do that even for projects that are well established with docs if I intend to depend on them.
If there actually were libs that are well documented and do the same thing, I wouldn't have started the projects I did but contribute to the existing projects instead. This may not be true for all kinds of projects.
You misread me. I almost never read the docs because they suck more often than not. I start from example and test source code and almost always end up reading parts or most of the source code.
I thought you were implying that you required libs you contribute to to be well documented.
Engineering making it work was a long way from operations making it reliable and understood.
I don't have unlimited time to figure out your code, API and lack of documents. I would rather deal with OSS or commercial software that respects me.
2. If you're designing tools for other people to use, documentation really, really, really matters. Even if it's just a mailing list and wiki initially.
When I'm evaluating tools, I look to the docs, and if I find them lacking, my interest dims very, very rapidly. I'm a systems admin, and don't do much coding (though programmers have a need for docs as well). My main concerns are uptime, reliability, predictability, and well-understood behavior. If a tool shows a wild cowboy shoot-from-the-hip, damn the torpedoes mentality, it's going to make my life (and my sleep quantity and quality) hell.
Life's too short for that shit.
If you want people to use your code, you need some kind of documentation. Otherwise, a lot of people (including myself) aren't even going to give you more than 30 seconds worth of time.
I'd prioritise a simple getting started guide. It only has to be a page or so, but something that explains how to run the program, and achieve a few simple tasks. It's far easier to go from a simple case to a more complicated case than it is to go from nothing to even a simple case.
To pick on a specific project, Treetop http://treetop.rubyforge.org/ has a pretty detailed set of documentation (human-generated, not automated), but I found it quite hard to go from the abstract enumeration of its features to actual working code. So hard, in fact, that I wrote up an introduction to help others, and it's been a very popular page: http://po-ru.com/diary/getting-started-with-treetop/
I want a conceptual overview, usage examples, and some discussion of edge cases.
I've rabidly documented my Rails authorization library, and I'd attribute most of the attention it's gotten to the documentation.
If someone were willing to make a video, writing text should be a given.
Many open-source projects also allow you to contribute to the documentation, so I don't think you should criticize projects you're actually using but rather that you should help maintain the documentation (even if it's just bug reports).
If you have an open-source project with very few users, you'll often find that you can't get traction simply because when people can't figure out how to use your software, they'll go elsewhere. Want fame and (maybe) fortune? Make your project useable.
How that documentation is written also matters. A lot.
Much proprietary documentation is also crap, for numerous reasons. Marketing having too much say is key (every reference to a Trademarked(r) Name(tm) Phrase(c) is both fully expanded and badged. Might keep the marketers and lawyers happy, but it's hell to read. Descriptions are vacuous to the point of idiocy ("More magic: select this option to enable more magic") -- tells me absolutely nothing not inherent in the control, and in particular, fails to tell me what the effect of enabling "more magic" is (feature name changed, but this construct is all too common in docs).
Usage notes and examples are mandatory.
As much as Free Software docs are pilloried, I still find that they tend to compare favorably with non-free docs.
Noted here: https://plus.google.com/104092656004159577193/posts/bLaDaXNe...
Software pushers all seem to give the same puzzled look when I ask to see their full docs before evaluating their product.
It's exactly as you describe, if the documentation isn't sufficient for me to learn everything I could possibly need and likely want to know about how things work - I can't confidently design, build, scale or support it.
Documentation in the "Enterprise" world seems almost intentionally bad, as if to force customers into professional services and support contracts for products which lack the proper design to be sold as full on SaaS.
There are plenty of other examples. Seriously, documentation is extremely important. Especially if you're relying on config files, document them properly.
also, writing a tutorial has helped me refactor and decouple parts of the lib a few times to simplify and hone the API to something much more elegant than it was in the beginning. sometimes i feel like Git could have used the same kind of process to create an much more refined, wart-free API also.
Not only is it much easier to work with something that is well documented but I also find as a general rule well documented projects seem to be maintained for a lot longer.
It's that you answer questions by pointing at the relevant section of the docs.
If that section doesn't exist, it's a good practice to see that it does (either write it yourself, have another contributor write it, or encourage the person asking the question to submit a doc).
And it's damn sure not something that good writers are interested in...unless they are paid. Paying good writers to write documentation is not a core competency of the FOSS community, nor part of its ethos.[2]
[1] These days being the age of the internet and languages implementing brogrammar. People like McCarthy and Knuth wrote their own documentation to a dead tree publication standard, not a rough draft of a Wiki standard.
[2] Erlang and Go aren't going to give the world another RPG or PG writing passionately about their wonders.
I know it's a drag. I know it's not that much fun. But it massively - MASSIVELY - improves the project's value, especially if it's low on the totem pole.
When we were largely buying shrink wrapped software they almost all came with decent sized manuals (quality varied, of course). He tagged the post with a bunch of open source projects, which has almost never been an area of good manuals. It's very uncommon for "scratching your own itch" to lead to comprehensive documentation for obvious reasons. Developers seldom write the extensive manuals, tech writers do.
http://www.ginandtacos.com/2012/09/24/tab-a-slot-b
In it, the author speculates that one of the reasons that kids have such a hard time following directions is that they never learn to read them, because nothing comes with directions anymore (you just "figure it out"). It's sort of the dark side of ubiquitous discoverable UI.
It provides immediate access to generally well-written and structured documentation and instruction covering a wide range of topics. The one downside would be the obvious lack of bleeding edge topics as those books have yet to be written.
http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-doc...
I can't be the only one to hear Dr. Strangelove's voice every time documentation is missing, can I?