Pick (or create) the most logical location for the document. Get a feel for the site's organization and fit the document where it most belongs.
Easy say than done. We need a site structure guide for this.
Please differentiate catalog/ and docs/. We have docs in catalog/, and front page and various places are linking to docs/ instead of catalog/ *sign* (note: I too think catalog/ is probably a lost cause, but it is more updated and organized than docs/index.html, so we should use it)
The catalog/ directory is used for listing documentation. Do not put the actual documents here. For general documentation links, please link to catalog/. docs/index.html is the old documentation portal and is no longer being updated.
For documents related to development and development processes, use the hacking/, quality/, projects/, unix/, and other project directories.
For other end-user, web-developer, and developer documentation, use the docs/ directory.
products/, about/, and developer/ directories are important top-level portals for new visitors. These pages provide concise introductory information and are meant to be kept up-to-date at all times. Do not put files here unless it is general purpose and you are prepared to keep them up-to-date.
Follow the branding guidelines when referring to Mozilla products.
The document is way outdated. And it appears we probably will never follow it (see bug 206838)
The page says nothing about NOWRAP and NOMENU. I think they are being overused.
Can we advise against using <dl> for indentation? wait, you are using it... damn.
But seriously, there has to be way of presenting structure without using indentation.
We should talk about Scope and Audience. I think every document should have either a specific topic or a specific audience. And ideally they should have both. Having specific topic/audience have many advantages:
* the document content is clearer * the reader can quickly skip documents s/he don't need * the document is usually concise and useful * it is easier to manage and update * it won't contain the WRONG information.
We should link to http://www.mozilla.org/docs/how-to-document.html
When Alec Flett wrote this document, I thought he was overrating the importance of audience and scope. Afterall, the writer should have an intuitive sense of what and to whom s/he is writing. But recently two things get my attention:
1. the about/ page is ugly. Andkon said it. fantasai said it. Many others and I said it. The page is ugly because it has no specific audience--it is targeted at every one--and because it has no specific topic--it tries to advertise, inform, persuade, and please ego. It is way too general, and it says many things and yet nothing. We need to avoid this.
2. My getting-started guide is losing its focus. I had a very clear idea of what I want--write something specifically for Mozilla 1.4. But over time, people suggest changes. I updated the paragraph on stable-vs-development-build twice or perhaps three times because people are being confused about user-orientateness of Mozilla. I ended up deleting the paragraph. Then Robert changed "Mozilla 1.4" to "%%mozilla-stable-build%%"... without checking if the document is up-to-date with latest version. (I protested but got lazy about backing it out.) Anyway, I had to made one change and remove the entire section "What's New in Mozilla 1.4".
In light of these, I suggest the following three sections:
*Scope and audience*: Every document should at least have a specific topic or a specific audience. Ideally it should have both. The document should clearly identify its purpose. This helps users finding information they want faster. This prevent other documentation writers from unwitttingly change the document scope and makes documentation management easier.
*Version applicability*: All documents get out-of-date eventually. In fact, expect your document to be out-of-date. Identify the applicable version clearly, for example, "this document is about feature XXX in Mozilla 1.4". Try not to use the term "version xx or later" unless you are certain it is true. This helps you avoid having to update small details frequently, thus potentially make the information inconsistant.
o *Server variable*: Avoid using server variables. Use server
variables in general purpose pages such as products/, projects
home pages, and download pages where the information is kept
general, non-version specific, and up-to-date. o *Download pages*: Download pages linking to the latest software
version/release/build should not contain any specific information
such as known issues, installation instruction, and feature list.
Such information should be in separate pages and linked. These
pages should clearly identify version applicability.*Updating documents*: Content document should be complete and thorough. When you add or remove something, you should review the entire content of the file and other related files under the same file heiarchy. Resolve any inconsistancy that may be present. It is unexceptable to have a document with a section applicable to version x and another for version y.
o *Scope*: Do NOT change the scope of the document.
o *Version Update*: If you change the software version number, make
sure all of the page content apply to the newer version. You should
test run and verify all instruction. o *Authorship and Ownership*: If you did not write or own a document,
Contact the page author/owner before makeing change to it. If you
make any content change beyond simple spelling and grammar, you
should consult with the page author/owner first (note: typo in
command/code instruction does not count as a spelling error). If you
think the changes are minor and safe, contact the author/owner
anyway after you made the change. In general, if you have made several major updates to a document
with permission from the author/owner, you can safely consider
yourself *a* maintainer of the page.
_______________________________________________
mozilla-documentation mailing list
[EMAIL PROTECTED]
http://mail.mozilla.org/listinfo/mozilla-documentation
