Organizing the Documentation Effort
Continuing from WeirdAl's post, here's a more coherent writup of what was discussed and concluded.
Doc Days
WeirdAl approached me last night about having "Doc Days" on Sundays, to collaborate on producing one document each weekend. He wrote about this on his weblog: How about we make Sunday "Doc Day"?
I think it's a great idea. However, for this to be most effective we need a definite, prioritized list of what documentation we need.
Organizing the Need For Documentation
If you take a look at developer-test.mozilla.org, you'll notice that there's hardly anything there. You can't go looking for holes to fill in because the whole thing is one giant emptiness. We need to split this up into manageable projects that can be assigned to people who want to help.
I want to work out a documentation framework so that
- we have a clearer picture of what we need to work on
- we can accept new documentation without it getting lost in the lack of organization
Now, I can organize docs both existant and hypothetical. At this point, though, I don't know what, specifically, the docs we need to organize are, so I'm having trouble creating an organization scheme.
Got suggestions? Post them to n.p.m.documentation in response to What are the top 5-10 developer documents that we need right now?
Documentation Bug Triage
Like practically everything on mozilla.org, documentation issues are tracked in Bugzilla.
Adding a READY State
I've filed bug 264721 on creatinga READY state in Bugzilla in response to Hixie's suggestion on aviary@. The state indicates that the bug is ready to be tackled — specs, bug description, testcases, crash data, etc. are all prepared. (Read mconnor's excellent analysis of problems in Mozilla's bug triage process if you want to hear more about this.)
For Documentation, the READY state would mean "This documentation request has enough info that a random person wanting to help will know what to do about it." In both cases, it makes it easy for new (and current) people to find something to work on.
Any Perl hackers interested in helping out?
Organizing Bugs by Type
Another problem we have with documentation bug triage is that there's no searchable flag to distinguish among
- coding change:
[FORMAT] - minor error-fixing:
[ERROR],[UPDATE] - major overhaul:
[OVERHAUL] - new document:
[NEW]
A person searching for one type often doesn't want an unfiltered search list that includes all the others.
This doesn't require changes to Bugzilla - summary radars (similar to
[AltSS]) would do fine.
Marking Required Skills
We need to figure out a way to categorize bugs by required skillset. For example, suppose someone's looking for something to work on and they know XUL but not C++. If we mark bugs with required skills, that person can restrict their search to READY bugs that don't require C++ hacking. Finding a good bug to work on would be easier. The same applies to documentation: if a person knows Perl, then he can work on stuff that a person who doesn't know Perl can't, and may want to specifically look for bugs that require Perl because of that (or, more likely, because he likes working in Perl).
We could use the Status Whiteboard for this. E.g. [SKILLSET Perl,
MySQL].
Documentation Infrastructure
WeirdAl commented that Bugzilla isn't ideal for solving documentation-related issues and suggested maybe looking for a more specialized issue-tracker. I pointed out that Bugzilla+Doctor+Wiki would create a sufficient infrastructure, and it would have less overhead.
Developing Documentation: Doctor
Doctor is well-suited to making small, quick changes. It doesn't help with the "major overhaul" and "new document" types of bugs, however.
Developing Documentation: Wiki
I don't believe that mozilla.org docs should be hosted on a wiki, but I think that it's a great place to work on them. There's no worrying about it being scrappy or disorganized at first. You can start an article, and multiple people can work on it at the same time. It's easy to do, anyone can help, make small/large changes, poke it around live...
CVS checkin is like publishing. The wiki would be like a public workspace.
Current workarounds for a workspace are
- using your own webspace
- using Bugzilla attachments
- checking in prematurely
None of these are good.
Once the document is polished enough, we'd file/hijack a bug to move it
from the wiki to mozilla.org. fantasai.bugs should be CCed
on the move so that I can assign a URI to the document.
Technical Requirements for Wiki
Besides standard editing, the we'd also need
- Some standard way to link a wiki article and its corresponding bug report. (Bug report would handle assignment, review/checkin process, etc.) The URL field of Bugzilla could be used for this.
- The ability to redirect from the wiki to the completed document on mozilla.org so that we can move the document to mozilla.org without breaking links that decide an in-progress doc is better than none.
Nilson notes that we also need direct editing of HTML/XML, not just wiki-style text editing.
Doc Days and Wikis - Interim Plan
MozillaZine already has a Mozilla documentation wiki, which we can use. It doesn't have direct HTML editing, but that won't become a problem until we get a significant volume of documents needing code transcription with the transfer to mozilla.org.
Alex Vincent (WeirdAl) will organize Doc Days.
Meanwhile, we can look into getting a dedicated wiki for developing documentation. It needs to be a simple and focused web service so that it's something easy to administer. (mozilla.org's sysadmin people have more than enough to do already.)
Communication
We need to make n.p.m.documentation a more useful resource. Use it to post updates and calls for documentation help. And if you write a blog entry about some ideas you have, post the url there! Not everyone reads everyone else's blog.
Marketing, Community, and mozilla.org's Direction
Some (slightly off-topic) critical comments I made got cut from WeirdAl's summary -
There are some documents on MozillaZine's wiki that are great and should be on mozilla.org but aren't due to marketing constraints. Their overview of mozilla.org's products accurately demonstrates the problem: This page is not targetted at mere downloaders—it's targetted at people really interested in Mozilla. But in mozilla.org's version the target audience is the exact opposite — it's targetted only at downloaders, leaving out useful information about the project.
The mozilla.org site seems to have lost its community focus. It's all about the product right now, which I guess is what end-users expect. But we're presenting ourselves the way a company would, not the way an open source project would, and it seems to be a generic problem with the high-profile areas of the site, not just the front page.
Got Comments?
Post them to n.p.m.documentation.