Last modified: 2002-04-03 11:22pm EDT Principles of URI design: A URI is a -permanent identifier-. It should be constant. The URI structure "should reflect the >>best logical organization<< of the documents on the server by exploiting its hierarchical nature."[1] Thus, there should be "a place for everything and everything in its place". The structure should create a coherent organization of the site's content. It must be extensible and highly forwards-compatible. So, if we decide someday to also create server software, we should be able to add necessary documents without disturbing anything else and still maintain a logical organization of content. In practice, this means Mozilla should not get special treatment. (You can still do whatever you want in terms of content and linking.) "The navigational structure is a web, more or less. But a good web--an /organized/ web--has strong spokes for filaments to attach to, and those spokes are the URI hierarchy. They maintain organization, provide a well- defined path for navigation, and can be oriented to when lost."[2] The URI Structure: This URI structure splits on what a visitor wants to do and then with what. This makes it easier for the visitor to find what s/he's looking for without having to know exactly what that is. mozilla.org/ | |--about/ - about the Mozilla Organization -- answers the | | question "What is the Mozilla Organization?" | | http://mozilla.org/mozorg.html | | | |--site/ - colophon for the mozilla.org website | | | |--community/ - newsgroups, IRC, mailing lists -- | | about the Mozilla community and where | | to find it | | http://mozilla.org/community.html | | | |--history/ - a history of mozilla.org | | | |--mission/ - mission | | http://mozilla.org/mission.html | | | |--people/ - who we are | | http://mozilla.org/about.html | | | |--sponsors/ - sponsors | |--contribute/ - How to get involved/contribute to Mozilla-- | | info on the rules, systems, and processes | | http://mozilla.org/get-involved.html | | | |--advocacy/ - Mozilla advocacy guides | | | |--evangelism/ - Evangelism guides, templates | | | |--hacking/ - general rules and guidelines for hacking | | | Mozilla code | | | http://mozilla.org/hacking/nutshell.html | | | | | |--checkin/ - Checkin rules/process | | | http://www.mozilla.org/hacking/rules.html | | | http://www.mozilla.org/hacking/bonsai.html | | | | | |--guidelines/ - coding guidelines | | | http://www.mozilla.org/hacking/best-coding-practices.html | | | | | |--write-access/ - getting CVS access | | | | http://mozilla.org/hacking/getting-cvs-write-access.html | | | | | | | |--application/ - CVS access form | | | | | |--review/ - all about the review process | | | http://mozilla.org/hacking/reviewers.html | | | | | |--guide/ - Reviewer's Guide | | | |--quality/ - overall QA stuff | | | http://mozilla.org/quality/ | | | | | |--bugs/ - bug writing guidelines and related resources | | | http://mozilla.org/quality/bug-writing-guidelines.html | | | | | |--_?_/ - much of http://mozilla.org/quality/help/ (maybe a | | triage/ directory?) | | | |--tools/ - tools for contributing | | | http://mozilla.org/tools.html | | | | | |--bugzilla/ - for use of Bugzilla | | | http://mozilla.org/bugs/ | | | | | |--bonsai/ - for use of Bonsai | | | http://mozilla.org/bonsai.html (top half) | | | | | |--cvs/ - for use of CVS | | | http://mozilla.org/cvs.html | | | | | |--tinderbox/ - for use of Tinderbox | | | http://mozilla.org/tinderbox.html | | | | | |--zope/ - for using Zope | | | |--writing/ - document writing/coding/uploading/style guidelines | |--dev/ - all software development-related information | | | |--_?_/ - Mozilla developers' stuff | | | |--web/ - Web Developer info - articles on writing pages for | Mozilla, FAQ, show-off section, etc. | |--events/ - All events for this year | |--legal/ - Licensing information, etc. | |--software/ - list of software released by mozilla.org w/ description | | | |--mozilla/ - intro & description for all of Mozilla | | | | | |--0.6/ - relnotes and stuff for 0.6 | | | |--build/ - build instructions | | | | | http://mozilla.org/build/ | | | | |--beos/ | | | | | | | | | |--mac/ | | | | | | | | | |--macosx/ | | | | | | | | | |--os2/ | | | | | | | | | |--unix/ | | | | | | | | | |--win32/ | | | | | |--distributors/ - link to Mozilla distributors | | | (e.g. Netscape, Beonex) | | | | | |--latest/ - Bleeding edge - getting nightlies, pulling | | | CVS tip, current build instructions, etc. | | | | | |--themes/ - list of themes available (elsewhere) for Mozilla | | | |--bugzilla/ - for using Bugzilla on your own system | | (subdirectory structure similar to mozilla/, | | above) | |--etc., | | |--news/ - news items (may be links to other parts of the site) | |--year/ - all news items for year | |--month/ - all news items and announcements for month | | (numerical - e.g. 05) | | | |--article/ - all files associated with the article, | directory named after article title | |--status/ - All status reports for this year | |--month/ - All status reports for month (numerical) | |--num/ - Status report, num = release date Notes on the URI Proposal: The creation of /software/mozilla instead of just assuming /software for mozilla prepares mozilla.org for the possibility of splitting the application into separate releases. It also provides a place for any other software released by mozilla.org. /contribute takes Gerv's /dev further. As the description says, it details *how* to contribute--code, docs, qa, etc. Much of http://mozilla.org/quality/ goes under /contribute/ qa/. Testcases can go in their respective /dev directories. Sections under /contribute link to Get Involved pages for individual projects. Splitting away /dev/web allows web-developer content to be more free-form. Web developers aren't going to view the separation of, say, the JS engine, the DOM, and the style system as sharply as we do. Docs for web developers are integrated. Docs for Mozilla developers are more separated; they are both organized and written differently, and the focus and purpose of their content also differs. This is why web-developer documentation should not be spliced into the various development directories. However, /dev/web can still link to docs in those directories! The use of dates for publications organization ensures a coherent structure regardless of topic--which is more easily addressed by an HTML page with descriptions anyway. Articles will frequently appear in more specific directories rather than in the /news hierarchy, but will always be linked from the month's index page. For the "project" directories under /dev (see separate doc), no project directory should hold another project's directory unless there is a very good reason to do so. Projects encompassing other sub-projects should link to them on the HTML pages. This way, a sub-project declaring independence won't damage the website's logic. BTW, this includes Mozilla. That's why you don't see a roadmap up there. Software directory vs. Development directory /dev All software development info; technical documentation goes here, along with related organizational stuff ex: people involved, project-specific news, non-dated articles and how-tos about Mozilla, freeze dates, etc. - no end-user documentation - no software is ever released from here, even if a project doesn't release source tarballs and only gives CVS & build instructions. Those instructions, along with any hype and suchlike go in /software. The only reason someone should wander in /develop is to develop software. Software documentation on mozilla.org is split into two categories: || Development Docs || Use Docs (not "User") | ||overview|documentation|project-org||overview|relnotes|build-instruc| -------||----------------------------------||-------------------------------| soft- ||what is |how does it |community/ ||what's |(self- |how to get it| ware || it? | work? |involvment || it do? |explain)| | /develop is for Development Docs /software is for Use Docs see separate document on the /dev hierarchy /software ALL mozilla.org's downloadable software: what they are, how to get them, how to install, how to use, langpacks, etc. /software provides one place for the visitor to see everything mozilla.org has to offer. This is where you get download and installation instructions (including build instructions). This is where we put all the advertising hype--developers know the software's features well enough and don't need filter through that. This is where we archive releases and their relnotes--developers are working on the bleeding edge and don't need that info. Everything in /software is targeted at people who come here to get the software. They don't have to filter through developers' news, technical notes, freeze dates, or any information on how it works or what the lead team is prioritizing right now. Mozilla distributions are linked from /software/mozilla; so are skins. Langpack releases also appear here, and any other paraphernalia that goes with the software. Everything's in one place, and because developers' docs are in /dev, content can be written around the "customer"--and potential contributor-- "don't forget to report any bugs", "Help us port Mozilla to BeOS!" etc. [1] http://fantasai.tripod.com/Mozilla/2001/reorg/OnURIs.txt [2] http://groups.google.com/groups?selm=3A5D16B7.5C43AEF%40escape.com Acknowledgements: writeup by: fantasai This URI scheme is the result of extensive discussions with Matthew Thomas and tweaking in response to comments from mozilla-reorg and netcape.public.mozilla.documentation.