2004-10-17
Continuing from WeirdAl's post, here's a more coherent writup of what was discussed and concluded.
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.
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
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?
Like practically everything on mozilla.org, documentation issues are tracked in Bugzilla.
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?
Another problem we have with documentation bug triage is that there's no searchable flag to distinguish among
[FORMAT]
[ERROR], [UPDATE]
[OVERHAUL]
[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.
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].
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.
Doctor is well-suited to making small, quick changes. It doesn't help with the "major overhaul" and "new document" types of bugs, however.
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
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.
Besides standard editing, the we'd also need
Nilson notes that we also need direct editing of HTML/XML, not just wiki-style text editing.
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.)
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.
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.
Post them to n.p.m.documentation.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。