Hello guys these are some of the thoughts I've had over the last
week on the issue of documentation for Mozilla. This is a long
message, so feel free to skim through the *main sections* (surrounded
by asterisks, or in bold). I've been following all of your messages
along so far, and have had comments that I have wanted to express, but
haven't been able to until now. So, here goes:
*On the file format we use for the Mozilla Help file* (HTML vs XHTML
vs Docbook vs XML + XSLT )
Currently, our help file is written in "plain old" HTML, not XHTML.
The advantages of using plain old HTML are: wide familiarity, wide
availability of cross-platform and both visual and text-based editing
tools (including Mozilla Composer, Homesite, Jedit and others).
About using XHTML instead of plain old HTML: The rules for creating
XHTML are stricter (e.g an XHTML document will not display when you
use <BR> instead of <BR/>) and less well known and supported by
editing tools. I tried opening an XHTML document in Composer and it
worked. But I do not know if subsequent changes made using Composer
will be valid XHTML. (I haven't tested Mozilla's support for XHTML
that extensively).
About using Docbook: I took a brief look at the Docbook format and
documentation � and it did look pretty complex. The consensus here
seems to be that Docbook is a complex format, and that we should be
cautious about using it.
Another choice which has not been discussed here as much is using a
simple self-invented XML format, which is converted into HTML (or
XHTML) by using self-invented XSL stylesheets. Gerv asked why using
XML is better than using HTML with stylesheets. Well, with
stylesheets, you can customize the attributes (colors, size, margins)
of existing HTML tags. With XML, you can have just the basic content
surrounded by basic tags. This XML document (and many others formatted
like it) can be transformed by a single XSL stylesheet into an HTML
document, with linked CSS stylesheets, and JavaScript files. For
example, consider the following XML snippet:
<helpfile>
<hbody>
<subsection>
<hlist>
<hlistitem>Item 1</hlistitem>
<hlistitem>Item 2</hlistitem>
<hlistitem>Item 3</hlistitem>
</hlist>
</subsection>
<subsection>
<hpara>The main help body goes here </hpara>
</subsection>
</hbody>
</helpfile>
This snippet of information could then be formatted using an XSL
stylesheet to look like a document in our current help file: a list of
the subtopics on top, with links to the sub-paragraphs in rest of the
document. The XSL stylesheets determines if the transformed document
is formatted using tables (as in our current help file) or using CSS.
By opening the XML file in Mozilla (which has an internal link to the
XSL stylesheet), you are able to see the transformed HTML document. My
point is: if we have a simple XML format we can agree on quickly, and
which can be edited by beginners and pros alike, then we might make
editing the help file as XML easier than as HTML (using Composer, for
example). The XSL stylesheet is only edited by the help file markup
team, not by every help contributor. In my opinion, this idea is only
feasible if: 1) we keep our XML structure as simple, and
self-explanatory as possible 2)We give clear instructions on what each
tag does 3)Beginners feel comfortable using it and do not mind not
knowing what the XSL stylesheets are doing in the background.
*About whether it is necessary to have a review and/or super-review
process* for approving documentation submissions: I believe some sort
of review mechanism is necessary. What we currently have is absolutely
no standardized system for reviewing and accepting submissions. This
lack of structure about what the process of review and approval is
hinders the contribution of new submissions considerably, because
potential contributors do not know what to do with the changes they'd
like to propose. They do not know what the process is; they do not
know who to talk to.
I think the current review process for code submissions is good,
because it allows anyone to submit proposed changes (via a bug
attachment) without having "insider connections" (knowing who to email
it to, and how to go about it). In my opinion, one considerable
problem affecting the Mozilla community and collaborative development
process is that it is very difficult for new contributors to share
their ideas, code, or documentation with the project.
*I think there is lopsided emphasis on contributing code, while the
contribution of ideas or documentation is given the short shrift.* An
example of this: Often, when a newcomer suggests a new feature or a
change in an established procedure he receives the following reply:
"Why are you just talking? Put some code on the table!". The problem
is: analytical thinkers/problem solvers (i.e. "managers") or
documenters who do not have (considerable) programming experience are
not given a formal place in the Mozilla collaborative development
framework. My point is: these people are important too, and the
lopsided emphasis on code contributions hurts the project, because you
end up with an "insider" driven structure which is hard for an
outsider to understand, and insufficiently documented features and
code.
Gerv has referenced ideas from Eric Raymond's essay "The cathedral and
the bazaar" several times: the "cathedral" vs "bazaar" method of
software development and the idea that you should "release early and
release often." In my very own opinion, I believe Mozilla's current
development process is not always purely a "bazaar" oriented one.
Mozilla 1.0 was always thought of by many as this mythical, near
perfect release (i.e., it needed to be a grand, tall, and beautiful
looking cathedral). If this was the result of an official policy of
mozilla.org or the product of the natural evolution of the product and
the challenges it faced along the way is a separate discussion. Again,
regarding "release early, release often" (as a good thing): Mozilla
has had nightly and regularly frequent milestone releases; but � the
first release where mozilla.org said "We are giving this an even
version number / this is a big release/ it is done, stick a fork in
it" was Mozilla 1.0. More than anything, the release of Mozilla 1.0
was a signal of confidence expressed by mozilla.org in the product
worked on four years, to the whole world. It was an official sign
which said "take a look at this, it is complete". But this signal of
confidence took a long time to produce. So, if you say Mozilla is
released often and early, then that is a statement which can be easily
challenged, since there has been only one "confidence release" until
now.
My point is: not all of the established procedures for Mozilla's
development are perfect. What we are doing in this newsgroup now, is
thinking about how we improve some of those existing procedures �
especially those related to producing documentation. Let's at least
listen to all the ideas put forth, before shooting them down.
*About using "the right tool for the right job", i.e. Bugzilla vs
Newsgroups for documentation discussion and creation.* While I agree
that it is easier to follow a discussion in a newsgroup rather than
one in Bugzilla, it is true that many discussions do appear in
Bugzilla instead of in newsgroups. In my opinion, one of the problems
which leads to this is that Bugzilla is being used for many different
purposes: keep track of defects ("real bugs"), feature requests
("RFEs"), series of related issues ("tracking bugs"), milestone
release guidelines ("Make Mozilla 1.0 not suck"), and finally
documentation issues too.
My question is: what is a bug? Is a bug all of these things? When you
say "use the right tool for the right job" or "use the existing tools
we have" there is the implication that there is a perfect tool for
every job, which is not the case. I would argue while Bugzilla is good
at keeping tracking of items needing to be addressed (and their
status), it is performing a lot of functions simultaneously � leading
to no widespread clarity about what exactly it is keeping track of. It
holds a treasure chest of information, but that chest is hard to sift
through.
My point: if we are to think about the long term production and
maintainence of documentation, we should be thinking about having
documentation-specific webtools (a "Doczilla" version of Bugzilla, if
you'd like) which address the needs of the documentation creation
process more specifically. Again, thinking long term is not
necessarily "cathedral" thinking; it is not something to be
immediately dismissed. It is thinking about a legitimate problem we
have (Bugzilla is doing too many different things to be as useful as
it could) � and that problem has to be addressed before it becomes
bigger.
Well, that's all I have to say. Thanks for reading this "digest
version" of a week's worth of thoughts. I look forward to your
comments.
Regards,
- Jay
