The below is not meant to be totally negative, but to stimulate debate :-)
Jayesh Sheth wrote:
> 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.
Be very cautious here. I'm sure several people have BTDT, and it would
be stupid to reinvent the wheel. Scour the web before we invent yet
another language.
> 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.
This is also true of semantic XHTML, with the added advantage that it
can be rendered (albeit plainly) by modern web-browsers. We could use
XSL stylesheets to transform it into cross-browser HTML with style
sheets and stuff, but it would also be renderable in basic form to make
editing it and previewing it a lot easier.
> 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).
This simple XML format is <p>, <em>, <strong>, <ol>, <li>, <br/> etc :-)
If you want even more semantic structure, it's <p class="introductory"> etc.
> 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.
My proposal meets all these criteria, and is familiar to almost
everyone, without much new learning required. Because it's XML, you can
transform it. Because it's HTML, people know it and you can render it.
> *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.
IMO you are conflating two problems. "They do not know who to talk to"
is the real problem. "They do not know what the process is" would go
away if they knew who to talk to, because that person would tell them.
> 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.
So the current code process has a high barrier to entry, and you want to
copy it? Again, also, you are conflating two things. The code process is
good because anyone can supply patches. This could be true of most
documentation processes; a code-style review system is not required for
it to be true.
> *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
This is code for "Go away, we are busy", but less negative. ;-)
> 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).
I don't know who gave them that idea - it certainly wasn't us :-)
> 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
No, it wasn't :-) It was an official sign which said "take a look at
this; its APIs are not going to change under you any more." It's
certainly not complete; no-one would claim that.
> *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?
Think of it as "IssueZilla" if it helps. :-)
> 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.
That's not the implication. Let me rephrase: "Use the most appropriate
tool available for each job." I believe newsgroups are the most
appropriate tool for the discussion we are having now, and Bugzilla is
the most appropriate tool for filing agreed actions and driving them to
resolution.
> 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.
You suggest this tool without saying what it would do. What would it do?
> have (Bugzilla is doing too many different things to be as useful as
> it could)
Bugzilla's usefulness for doing X does not decrease because other people
are doing Y, Z and Q with it.
Gerv
