7 ms·
WTFM - Write The Freaking Manual
- exDM69 14y agoWhen it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don't like at all. Guess which I am going to pick. 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.
- orangethirty 14y agoYou can run the source through one of those automated documentation tools like doxygen. That does make a big difference.
- threedaymonk 14y agoHonestly, I'm not sure it does. I've seen plenty of software projects whose documentation consists of an automated compendium of every method in every class, none of which tells me how to actually use it. 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/ 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/ http://po-ru.com/diary/getting-started-with-treetop/
- nathan_long 14y ago+1. If I wanted to rummage through a pile of classes and methods to figure out where to start, I'd just read the code. 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. https://github.com/nathanl/authority https://github.com/nathanl/authority
- deleted 14y ago[deleted]
- xradionut 14y agoI've wasted hundreds of hours dealing with piss-poor or no documentation, reading/debugging code, searching sites and forums just to find the magical combo of steps that get a application to build correctly or an LED to blink. 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.
- Swizec 14y agoConversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library. 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.
- exDM69 14y agoGitHub READMEs are an excellent compromise. Doing more detailed docs are quite a lot of effort (that is better spent coding), especially to projects that are at an early stage. 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.
- rgbrgb 14y agoThere's a double standard here. You want developers to contribute to your project despite the lack of documentation but you require that libraries you contribute to are well documented.
- exDM69 14y ago> ...but you require that libraries you contribute to are well documented. 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.
- rgbrgb 14y ago> If there actually were libs that are well documented and do the same thing... I thought you were implying that you required libs you contribute to to be well documented.
- nathan_long 14y ago> I can spend time writing code or writing documentation. 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-development.html http://tom.preston-werner.com/2010/08/23/readme-driven-devel...
- protomyth 14y agoI remember reading a story about Pages for Pages on NeXTSTEP. The manual was done before the software, so if there was any design question about how the program should work, they turned to the manual. I think it was an article by Bruce Webster (he is an awesome writer).
- dredmorbius 14y agoThat's a code authoring technique I picked up from Code Complete. 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.
- xtracto 14y agoBut the thing is that he is not selling himself at all. He writes some code for him and then maybe decides to release it as open source in case someone else finds it useful.
- radiac 14y agoPeople who release undocumented code have no sense of social responsibility, and they are wasting everyone else's time. 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.
- nollidge 14y agoThe sweet spot, I think, is a nice "getting started" guide along with an discoverable API design. The guide gives prospective users an idea what it's like to use the library, and the discoverableness means they'll be able to figure out the more complex stuff without precarious trial-and-error or obscure doc spelunking.
- dredmorbius 14y ago1. Figure out a way to get paid for it. 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.
- burntsushi 14y agoI think this is all well and good, so long as you're not looking to get people to use your code. 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.
- tsahyt 14y agoYes, this. I'm looking at you, freedesktop.org... PulseAudio documentation is poor. Considering it doesn't really work out of the box on half the systems out there that's pretty bad. fontconfig docs are some of the worst I've seen in a long time. In general, I feel dizzy when I find a link with "freedesktop.org" in it labeled "docs"... There are plenty of other examples. Seriously, documentation is extremely important. Especially if you're relying on config files, document them properly.
- orangethirty 14y agoAnd please, run your source through a tool like doxygen for me to get a better understanding of how your software is built and designed. I've been advising a startup that is facing issues with documentation not being available for the platform they chose to use. The platform looks good, and the code is fairly readable, but there is no documentation. To complicate things, the platform is under active development and things change weekly (if not daily). The solution? The startup is looking to have their application written in another platform. All we need is for you to explain how stuff works in a language that even a grilled cheese sandwich will understand.
- fellars 14y agoAny pointers on how to make it easier to wtfm? If anyone out there actually enjoys writing documentation I'd be willing to pay for some help and guidance on a rather large commercial open source project that is in need of some tlc regarding documentation
- tsahyt 14y agoAPI documentation can be generated from the source code with tools like doxygen. For everything else there's the standard toolchain consisting of a good editor and source control. Writing documentation is a chore but it's a very important aspect nevertheless.
- qznc 14y agoSphinx is pretty nice, even if it is not a python project. http://sphinx.pocoo.org/ http://sphinx.pocoo.org/
- takluyver 14y agoIn the Python world, readthedocs.org has made writing docs easier - it takes care of rebuilding documentation each time you commit. It's implemented in Python, and most popular with the Python community, but it can be used for other languages as well.
- FiddlerClamp 14y agoI'm a marketing and technical writer - take a look at the URL in my profile and get in touch if you are interested.
- norswap 14y agoI couldn't agree more. The lack of good documentation is a plague which is not emphasized quite enough. To me it is as (or even more) important than writing tests: debugging code is easy in comparison to figuring out what it is supposed to do in the first place.
- smoyer 14y agoThere are actually many open-source projects that have excellent documentation and there are many that don't have documentation at all. I think there's actually a shortage of projects with simply adequate documentation. 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.
- jackalope 14y agoAnd please, WTFV isn't enough. I don't have time to watch or search through a 40 minute video to find out how to set a few configuration options. Text is king when it comes to documentation. Videos are fine for tutorial purposes, but I need a solid reference that's well indexed and searchable.
- nathan_long 14y agoVideo is also a poor replacement for text because it is MUCH more laborious to create and update, so it probably won't be updated. If someone were willing to make a video, writing text should be a given.
- jobu 14y agoGood documentation is really hard to do, but it's also one of the most important things for any product or project. If no one uses what you make then it truly is useless, and you will never get people to use something unless they can figure out how.
- jiggy2011 14y agoTo be honest, good documentation is more or less my #1 criteria for choosing which library to use. 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.
- ubernostrum 14y agoAmusingly, I gave a talk with pretty much this exact title at DjangoCon last year, and am submitting an updated version of it for PyCon next year :)
- kerv 14y agoI'm pretty sure that if there was a manual for the software or application you are using, you wouldn't read it anyways. The software should be intuitive in the first place.
- leeoniya 14y agoi'm currently writing a tutorial/manual for a library i wrote several months ago. the library took maybe 1 month to write and now the tutorial has taken 3 months. creating examples, illustrations, demos, determining and writing the sections in a sensical, progressive order takes a long time (epecially when it's done in your free time) :(, but without it, the project is DOA and no one will use it. 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.
- crazygringo 14y agoI would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. 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.
- Zelphyr 14y agoYou mention CoffeeScript being one of the worst, and I don't necessarily disagree, but how has it become so popular despite its poor documentation? Is it because CS is just /that/ good? Or is it that it has developed a great community early on that compensates for the lack of documentation? Either way, writing good documentation seems like an either path than doing those two things.
- adhipg 14y agoThere's also a third reason: it's very easy to see what CoffeeScript compiles to - the JavaScript source is easy enough to read and comprehend - and that behaviour is well documented. Most of the times I'm looking at CoffeeScript to just figure out what it compiles to!
- trotsky 14y agoReminds me of the old expression: "fast, cheap, good. pick two." 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.
- Zelphyr 14y agoI think his point was more that clearly the developers want people to use what they built. So taking that extra step and writing good documentation would only help ensure that people used their software. Not doing so actually hurts their chances. Not doing so and expecting SOMEONE ELSE to do it is just dumb.
- todd3834 14y agoI agree with the author, I have found myself in similar situations and it is frustrating. However, I also think programmers need to RTFSC (SC == Source Code)
- aidenn0 14y agoI think after you write a manual for your first few projects and clearly less than 1% of your users read it, it gets hard to motivate yourself to write another manual.
- dredmorbius 14y agoThe advantage of documentation isn't that users read it before asking questions. 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).
- tibbon 14y agoI've been trying to get better about just helping to fix the documentation when its bad- but that is dependent on me being able to figure it out in the first place with broken/poor docs.
- _lex 14y agoI agree - I often just give up and read the source to figure out how to use advanced features.
- ternaryoperator 14y agoAnd while we're at it: Javadoc is not a substitute for writing documentation.
- dredmorbius 14y agoI fully endorse this. Coming from a sysadmins / devopps perspective, documentation is key to providing a reliable, dependable, available, scalable service. And dramatically improving the quality of my life. 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/bLaDaXNeJu4 https://plus.google.com/104092656004159577193/posts/bLaDaXNe...
- incision 14y agoComing from the same perspective, I agree completely. 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.
- brudgers 14y agoThe root of this issue is that writing documentation is not something that really good hackers like to do...these days [1]. 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.
- pnathan 14y agoOne thing I've done a few times is to help out just by writing docs for open source projects. 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.
- brudgers 14y agoBut of course, your profile lists lisp.
- trhtrsh 14y agohttp://golang.org/doc/ http://golang.org/doc/ http://research.swtch.com/ http://research.swtch.com/
- mmariani 14y agoHere's a great approach to solve this issue. Also, it's a good talk too. http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-documentation-driven-development-4896872 http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-doc...
- 1337p337 14y ago"The whole point of the Doomsday Device is lost if you keep it a secret. Why didn't you tell the world?" I can't be the only one to hear Dr. Strangelove's voice every time documentation is missing, can I?
- incision 14y agoThis is one of the reasons I consider my Safari subscription indispensable. 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.
- blahedo 14y agoRelevant, I think: http://www.ginandtacos.com/2012/09/24/tab-a-slot-b 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.
- orangethirty 14y agoThere is a big need here waiting to be satisfied. Documentation is very important and a lot of projects are losing traction due not having the basics or it being done poorly. I'm actually working with a new platform by writing their documentation for them. Why would I do that? I have a talent for it, and it allows me to offer a service other full-stack engineers won't even think about doing. Writing documentation as a job is a great way to improve my engineering skills. If I can explain it to people, then I definitely know how something works.