Warning: I meant what I said in http://www.mozilla.org/events/dev-day-feb-2004/mozilla-futures/ about shamelessly imitating MSDN. I think many things about it that we can imitate are "good enough".
(Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd be happy to hear fast proposals addressing the issues below that everyone reacts to by saying "yes, this is it." I personally think there is no ideal document hierarchy, and that flatter is better. Redundant links and indexes help.
As we bring up DevMo, we should not worry about links working; until we "launch" the site to the masses, we must be able to fix mistakes as we go. Moving fast trumps moving with utmost care and caution. Bite-sized editing and fixing/polishing trumps "get all 100 pages perfect before releasing them." Marshalling volunteers with good reputations in parallel is key.
All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers?
Anyway, some top-down ripoff thoughts:
MSDN has these links along the top:
Top dark blue bar, right justified: Microsoft.com Home | Site Map
Lighter blue gradient with MSDN logo on left
Main toolbar, light blue gray bar: MSDN Home | Developer Centers | Library | Downloads | Code Center | Subscriptions | MSDN Worldwide
Odd terminology: "Developer Centers" means "Topics"; "Code Center" means "Samples", it seems to me.
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
We could leave out Subscriptions and Worldwide for now, or stub them out and call for volunteers.
Library is where I think we should start building first and fastest. The three-frame UI seems good to me, but if someone has a better idea, please post it. The "MSDN Library Archive" hierarchy tree widget has these rows at the top level:
Welcome to the MSDN Archive Component Development Data Access Enterprise Development Graphics and Multimedia Networking and Protocols Office Solutions Development Setup and System Administration Visual Tools and Languages Web Development Windows Development XML and Web Services
When you go to Library from the toolbar, though, you get a list of Most Recent Articles.
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
CSS
Gecko Embedding APIs
HTML
Java
JavaScript
JavaScript Debugging APIs
MathML
Python
SVG
Venkman User Docs (there's a great site at http://www.svendtofte.com/code/learning_venkman/ -- maybe we could host it?)
XBL
XML
XPath
XPCOM
XPConnect
XPInstall
XSLT
XUL
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.
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.
- How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.?
- Do we want a wiki front end? Shaver has argued that we do, based on his recent experience.
- 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/).
- 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?
- 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.
- 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.
- 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.
Let's go! DevMo!
/be _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
