Monthly Archives: August 2006

More on Writing Documentation

Jono has been writing lately about open source communities and how to make it easier for people to get involved. While I could quibble with the details, I agree with the principle. People contributing to open source projects shouldn’t have to deal with technical details. Art guys should know the intricacies of Inkscape, but not SVN and bugzilla. Coders should (just) deal with code, documentation people should deal with documentation.

From the documentation perspective, I don’t agree that documenters don’t need to know markup languages.

To me, writing documentation is a form of teaching. A documenter’s job is to instruct the user in how to do what they need to do. Documentation should make things clear, spur ideas, and empower. It should give the reader mastery of the software and enable them to integrate it into their brain as a tool. Documentation should do all this as quickly and clearly as possible.

To meet this end, document writers need to be as structured and organized as possible. We need a high level overview of the problem so we can break it down for the reader. We think in terms of the hierarchy and flow of a document. Just as an essay needs to have an opening paragraph, supporting points and a conclusion, a User’s Manaul needs a certain sructure that follows the way a user will look for help.

So a markup language of some type is essential. Be it HTML, wiki markup or DocBook/XML, we need to be able to structure documents. The problem is most markup languages suck. HTML works great for web pages but it makes sloppy documentation. Wiki markup is quick and easy, but it’s too limited. DocBook/XML forces the writer to use good structure and hierarchy, and takes care of a lot of the tiresome details (like table of contents, and nearly all presentation markup) but the learning curve is pretty rough. It is needlessly complex for most things.

The solution?

We need more accessible tools. For documentation we need a more usable subset of DocBook, or maybe a whole new XML application designed for software documentation. I hear something like this is in the works. We also need editors that can handle whatever format we settle on. I’ve tried various editors and in the end I’m more productive editing in Vim and doing all the markup manually.

If we’re actually going to solve these problems we need to do away with the edit-patch-submit cycle altogether. What we’re doing in Jokosher is a good example. We did almost all the documentation for 0.1 on the wiki, then generated our final docs from that. It still required a lot of manual work to get from wiki output to the final HTML, though. Now that we’re moving to DocBook/XML, the situation is worse. We’re building a new site that will support editing HTML and DocBook directly on the wiki, but the tools are still not there yet. We will need to modify existing tools to get what we want.

We need an infrastructure that supports contribution, but who builds this infrastructure? I’ve seen good projects suffer because there are people who would love to contribute, but just can’t get their foot in the door. Again, the Jokosher project has solved some of these problems. We’ve taken the time to write “Getting Involved” documents to give people step by step instructions to contribute. We’ve got forums and wikis and clear documentation for developers. All this stuff takes time away from development, but building a community that allows people to get involved means a better project in the long run.

10 things I learned about marriage

I’ve been married a year as of last Monday, Aug 7. In the last year I’ve learned a lot of things, and thought I’d put a few of them down. If you’ve been married for a while you probably know this stuff, but maybe it will benefit somebody.

  1. “OK I’m ready to go” doesn’t mean she’s ready to go. Wait until you hear that 3 times before you bother putting on your shoes.
  2. Just because she’s upset doesn’t mean it’s your fault. Women can get upset about anything or nothing. Do yourself a favor and don’t get upset just because she’s upset.
  3. Just because it’s not your fault doesn’t mean it’s not your problem. Whether you did it or not, you’ll pay for it. It’s best to get to work listening to what she has to say and seeing if there’s anything you can do to make her feel better.
  4. Just because the dishwasher is done doesn’t mean the dishes can come out and be put away. Dishes have to be shaken and manipulated in a certain way only she understands and left to dry for an additional period of time before they’re usable.
  5. Even if she’s wrong, you need to say you’re sorry. She can be so wrong that you can draw up a written mathematical proof of it and take her through it step by step to show her she’s wrong, and that won’t change anything. In fact it will make it worse. Give up and just say you’re sorry.
  6. Put the toilet seat down. I know it’s not fair because she never leaves the seat up for you, but you’re a man. Deal with it. It’s not worth the trouble.
  7. The fact that you stood in front of a room full of people and swore to her and a member of the clergy that you will love her always means nothing. In her minds it’s not a binding contract that’s in effect forever. You’ll have to keep telling her you love her over and over. She won’t get tired of it but you will, so find new and creative ways to tell her and show her you love her. After a while you’ll even start to enjoy it.
  8. You can live with 2 pairs of shoes. She can’t. It’s a need, not a want. I don’t know why.
  9. You are the man, which means you are in charge. You are stronger, and you’re a leader. The only problem is you’ll have to convince her you’re in charge by being worthy of respect. A leader isn’t someone who beats other people into submission. You’ll have to work hard to show her that she can trust you to lead, and that you’ll do the right thing no matter what. She needs to know you’ll suffer so she doesn’t have to before she’ll even begin to trust you. Chances are someone did a really bad job of this before you, which makes it much harder.
  10. Sleeping with the same woman every night is better than sleeping with a different woman every night. Doing the same thing over and over doesn’t get boring, it just allows you to pick up on details you didn’t notice the first 100 times. You have to pay attention, though.