Proposal: we have our own look, but with similar bars along the top:
- highest has some few right-justified items to get to www.mozilla.org and a sitemap;
- next has a gradient and a left-justified "DevMo" logo, or something as simple yet attractive and even more distinctive;
- lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide
Sounds fine, except categories would do well to be driven by readers.
Library is where I think we should start building first and fastest.
Hmm. Reference material isn't a big reader drawcard, and takes a long time to create. We could chuck up what we already have and then focus on better titbits.
We will hope to get to the point of having so many articles, and such a stream of fresh ones, that we can or must do likewise, but for now, it seems better to me for us to have docs organized in a fairly flat category tree that organizes and includes at least:>
> ...DOM (doron has a plan for these docs, I understand) DOM Inspector
Eek. Eek. Readers First. These are all subcategories for readers who want reference material.
We definitely want tutorials organized by hot "How do I do X?" questions and scenarios. Guides and other longer docs that cover larger APIs and sets of APIs are needed.
Written for beginners? For experts? For Uni Students? For teachers? For who?
Architecture and user-interface laundry-list:
- Need a graphical design strawman or mock-up that we can all nitpick into shape and agree on, soon.
Yay. That's fun.
- How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.?
The content part is words (and code) for most one-off pieces. You just fill a template with words and code in one spot. Anything else is server-side includes. Maybe you have to split the article across a few pages by hand.
There's always special cases, like the keyboard map page. But mostly you just cut'n'paste the content in. Maybe you have a Perl script that takes the plain text and hacks it a bit before you paste.
- Do we want a wiki front end? Shaver has argued that we do, based on his recent experience.
For one class of readers. It's a community forum / community service. It's not for everyone.
- What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/).
I voted elsewhere for something like a CMS that can give a document a number rather than a path (paths contain a hardcoded hierarchy).
- We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk?
Only needed for docs with long review cycles; mostly reference. Needed there, though. Note that OpenOffice/Word allows two copies of a draft with different comments to be merged into one. So it doesn't have to be done server-side.
- Should we let programmers use doc-comments to write primary API document source, and extract it via a javadoc style tool that grovels over the source tree, compiling XML or HTML from the extracted comments and their context? I think so.
Just ask Neil Deakin for his xulplanet gear, then. It would be better to give the reader a fishing rod than a fish: explain how to read XPIDL. It would be great to encourage extra documentation in .idls, and reflect the lot to the Web.
- Should we implement an idea of Ben Goodger's, doc-comment tags of some kind to bracket "best practice" or otherwise canonical examples? Again, the idea is to let programmers keep primary doc source in the code, where it is less likely to rot.
Any documentation generated by developers is nice to have, but in my view, implementation notes are the best use of core developer time on docs. There's another tier of people who can take that info and produce examples, etc. There needs to be a medium where those implementation notes can be announced, eg to mozillazine.
- Lxr queries linking API interface and method names to their uses.
- Benjamin Smedberg has good experience and ideas on how the back end and an initial HTML front end should work, what the meta-data should be accompanying the documentation data, etc. Benjamin, please comment when you have the time.
Nothing beats a lovingly crafted hand woven basket ;-) These things would help content providers write better articles for sure, though.
- N. _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
