How about we make Sunday “Doc Day”?

… and on the seventh day, God rested. So do most of our developers, for very good reasons. Sunday is usually the lowest traffic day of any day in any IRC channel.
But we still get people in the channels asking for help. Less, certainly, but not zero.
I’m thinking Sundays would be great days to have a “Doc Day”, where we just go through the source code and the docs on mozilla.org and see what we can turn up that needs fixing and/or writing down. The various trees are usually very stable on the weekend, with few checkins.
So what would a Doc Day entail?
At first, not very much! When I tried kickstarting documentation a couple years ago, I fell flat on my face, mainly because I tried too hard to guide everything in a certain direction and we didn’t have enough feedback. We might still not get enough feedback on Sunday, but this time around I can afford to linger for 12 hours at a time online.
Probably we’d start out mainly by picking an area that someone wants doc’d, and we’d spend a day on it, gathering notes. Somewhere late in the evening Pacific time (say, 5 pm), we’d probably call it quits on note-taking and gather around one place to start compiling what we learned into a document or two.
I’d host it on my blog (thanks to my saveAsFile.js script), and we’d gather in a channel like #mozillazine to nitpick it and polish it to a submittable draft. The goal would be one major document (an article, an interface’s implementation, etc.) a week. Then, I’d probably ship off the draft to Asa or someone else who cares, and we’d get it posted.
One document a week. I think it’s doable. Who’s willing to help?
UPDATE: But not this Sunday. This Sunday, two of the hottest teams in football this year are going head-to-head. One of them happens to be that of my hometown, beaten only once this year. The other is the defending Super Bowl champions, unbeaten for nearly 20 games.
I’m beginning to think that I’m the Rodney Dangerfield of Mozilla development. I get a lot of things wrong, and that’s why I don’t get no… 🙂

6 thoughts on “How about we make Sunday “Doc Day”?”

  1. I think you should work within the framework of http://developer-test.mozilla.org/contribute/ .
    Please realign your work with them. Your proposal is neither new, neither will it work this time. All these proposals have not worked until now as you need to understand what you are documenting, this very often requires that you are developer.
    I believe you will be far more efficient if you ask the nice people behind devmo, where they need help and just do it and try to encourage with your blog people to follow your path.
    (From Alex: I believe I’ve just been insulted, mildly. I thought I was a developer. Maybe a second-rate XUL developer compared to the heavy hitters already on the team, but still…)

  2. Arrgh, did I forgot the main sentence:
    “Real programmers don’t write documentation.”
    Sorry. But the point is you will not convince developers to sit down and document.

  3. I don’t think that’s meant as an insult in any way. Bernd was saying that “unless you’re the one writing/owning the code, you probably can’t document it as well as it should be done” which is pretty true for backend API code. I don’t think someone can just read code and document it unless they know the code really really well.
    (From Alex: I just figured that out this morning. I thought Bernd was talking about me, when he was really talking about the community in general.
    On the other hand, a few years ago I was just a guy who liked to tinker with JavaScript and web pages. I didn’t really know anything about coding then, and writing a book taught me a lot.)

  4. I don’t think someone can just read code and document it unless A) they know the code really really well and B) they’re a strong writer.
    To get really solid documentation, the owner of the code really ought to be collaborating with a professional writer. Unfortunately, large open source projects tend to have plenty of developer volunteers, but hardly any tech writers. I’ve never really been sure why.

  5. I, for one, am all for the idea. I think you should also circulate this idea to other doc writers (not veryone reads blogs).
    I think Sunday is pushing a little bit. I prefer Saturday because, that way, if you can’t finish a doc in one day, you can finish the next day, when the ideas are still fresh in your mind.
    While it’s preferrable that developers document their own code, the fact is that they don’t. So what do you do? Try to convince them to do it or try it on your own? We are lacking d11n, and incomplete and unofficial documentation is better than none at all. Also, most of the source code is well documented. If you understand some C/C++, you can probably figure things out yourself (for example, I wrote this by reading the source code).
    Have you asked kerz about this? We might get more participants if someone can change #mozillazine topic to “Doc Day: go to #documentation to help” on weekends.

  6. fyi sunday is the first day od the week not the seventh
    (From Alex: That depends on whose calendar you go by. But it’s really a moot point in this context…)

Comments are closed.