Per bernd’s comment a few days ago, I had a little chat with fantasai about potential “Doc Days” and the overall documentation effort. I have a rough summary (posted in extended entry) of what we talked about, courtesy of fantasai

. We’ll be seeing a blog later from fantasai about this in some more detail.

fantasai: WeirdAl posts blog entry about Doc Days
fantasai: https://weblogs.mozillazine.org/weirdal/archives/006711.html
fantasai: fantasai notes concerns with not having a good idea of what documentation needs to be written
fantasai: and therefore not a good idea of how it should be organized
WeirdAl: (roadmap bug)
fantasai: fantasai filed bug against Bugzilla for a READY state
fantasai: which Hixie requests for handling regular bugs
fantasai: (state represents bug ready to be tackled – specs, testcases, description, etc. all good)
WeirdAl: checkins? 🙂
fantasai: would be useful for docs as well – this request has enough info that random person wanting to help will know what to do
fantasai: another problem with doc bug triage:
fantasai: no flag to distinguish
fantasai: – fix minor errors
fantasai: – major rehaul
fantasai: – write new doc
fantasai: different kinds of bugs
fantasai: people searching for one often don’t want to look at unfiltered list including others
fantasai: WeirdAl considers documentation-specific issue tracker
fantasai: fantasai suggests that Bugzilla+wiki+doctor would probably be sufficient
fantasai: and has less overhead
WeirdAl: weirdal agrees
fantasai: fantasai notes:
fantasai: I don’t believe that [mozilla.org] docs should be hosted on a wiki
fantasai: but I think that it’s a great place to work on them
fantasai: start an article
fantasai: and multiple people can work on it at the same time
fantasai: it’s easy to do, anyone can help, make small/large changes, poke it around
fantasai: and not worry about it being scrappy or disorganized at first
fantasai: — like a public workspace
fantasai: CVS checkin is like publishing
fantasai: current workarounds are a) use your own webspace b) use bugzilla attachments c) checkin to mozilla.org prematurely
fantasai: none is good 🙂
nilson: So you were proposing to use kb.mz.o?
fantasai: weirdal looks around web, notes existance of www.naturaldocs.org
fantasai: yes
fantasai: points out that auto-generated docs don’t handle XUL etc
WeirdAl: (I should note that my thinking at the time was on the level of source-code docs)
fantasai: –
fantasai: Doctor is great for handling “minor errors” category of problems
fantasai: “rehaul of existing docs” and “write new doc” should ignore diffing
fantasai: would be useful to have wiki for document development
fantasai: we look at kb
fantasai: wrt wiki, would need (besides standard editing of articles)
fantasai: a) linking wiki article to bug report (URL field of bugzilla?)
fantasai: b) redirecting to completed document once its done
fantasai: so can move doc from wiki to moz.org
fantasai: but not break links that decide in-progress doc is better than none
fantasai: c) wiki needs to allow direct editing of markup
fantasai: –
fantasai: wrt bug triage, need to categorize by skillset
fantasai: someone looking for something to work on may know XUL but not C++
fantasai: so being able to restrict search to bugs that don’t require C++ would be good
fantasai: someone knowing Perl might want to restrict search to bugs that /do/ require Perl
fantasai: etc.
fantasai: applies for documentation too
fantasai: weirdal notes that the tree components for docs in bugzilla are mostly useless
fantasai: consider various reorganizations, nothing conclusive
fantasai: fantasai pulls up kb summary of mozilla products
fantasai: http://kb.mozillazine.org/index.phtml?title=Intro_:_Summary
fantasai: points out that there is lots of useful info there
fantasai: but it’s targetted at people interested in mozilla project
fantasai: not downloaders
fantasai: whereas mozilla.org’s products page is exact opposite