On 10 Jul 2002, it is alleged that Mitchell Baker sauntered in to
netscape.public.mozilla.documentation and loudly proclaimed:
> sorry if this has been answered, but I"m just catching up from a bit of
> time away.
Hi, Mitchell:
No probs. We're just trying to hash things out here.
> Are you proposeing that this process be followed for all docs, including
> devleoper docs? I saw mail from brian saying that developer docs are
> included in the reorganization, but I couldn't tell if you meant this
> process as well.
There seem to be four sets of docs that we're dealing with: developer docs;
what John Keiser has been calling 'technotes', which should serve as the
basis of docs that can be targetted at OEMs; web-dev docs; and user docs.
(The last isn't going to go over well with some people within the community,
but I believe that this can be done without necessarily betraying the
development aspect of mozilla.org and without necessarily having a negative
impact on the various distros.)
John Keiser seems to feel strongly that Zope is ideal for technotes. In the
other three cases, there seems to be a growing consensus (I've just popped
back in here after a couple days away, so I could be wrong) that Zope's
strengh lies in development. For developer docs, it provides a good way to
get input and to try to maintain some currency in the documentation provided
on mozilla.org. Web-dev and user docs are a bit different, since it's less
imperative to maintain them.
> I'm picturing one of our key developers who finally gets around to
> writing amuch needed doc on strings implementation, or correct XUL
> syntax, or other deeply technical subjects. Are you proposing
> developers use the process below?
The process out-lined below is a bit problematic; according to fantasai, for
instance, it's not possible (at least right now) to automate a CVS up-date
within Zope. The idea of a trial period is an interesting one, but I can
see major problems with implementing it.
What I'm suggesting is that moz.zope.org be used for initial and on-going
development. In your example, a draft doc would be developed on
moz.zope.org, and any necessary r= or sr= work would occur there. The
problem I see with the idea of a trial period is with publicising it; off-
hand, I don't know a way in which to deal with this in a functional manner.
In addition, we have been discussing the idea of having someone who would
deal with editorial issues, sanity checking, and the like; this is what I
refer to below as 'ownership'. Roughly, the idea is that there be someone
(not necessarily a fixed individual) who would be concerned with maintaining
the doc as such (rather than its content).
> And do mean that a doc is moved to a zope server for +every+ edit?
No. The idea would be that development of a doc would occur on moz.zope.org
(or equivalent) with that doc then being 'published' to mozilla.org /via/
CVS as necessary (how often might be necessary is another matter). I think
this would allow for documentation to grow 'organically' (as Gerv suggested
in one of the threads here) while also allowing documentation of mozilla.org
to be more readily maintained. Keeping a revision history separate from CVS
blame would also seem to have its advantages.
There is at least one other major issue that needs to be dealt with,
regardless of the path taken by any d11n re-org, and that's some sort of
functional cataloguing or indexing system. FWIU, it should be possible to
maintain a consistent URI structure between Zope and CVS; the real issue is
just how to go about such a catalogue or index.
Don't know if this clarifies anything; at any rate, I hope it does.
Brian
> Mitchell
>
> Brian Heinrich wrote:
>
>> On 07 Jul 2002, it is alleged that s.m. koppelman sauntered in to
>> netscape.public.mozilla.documentation and loudly proclaimed:
>>
>>
>>>Brant Langer Gurganus wrote:
>>>
>>>>After reading some more about other people's opinions and my own, so
>>>>far this is the best scenario from what I have assimilated:
>>>>All documents are initially hosted on moz.zope.org.
>>>>After a change of a document, it is hosted at ZOPE for a trial period.
>>>>If a change must be made, it is made and the trial is extended.
>>>>If no change is necessary during the trial, it is made "official" and
>>>>copied to mozilla.org.
>>>>If it later becomes necessary to edit the document, it is edited at
>>>>moz.zope.org with another trial period.
>>>>Like the original publication, it is moved to mozilla.org if it
>>>>survives the trial period with no modification.
>>>>
>>>IMHO this ignores the natural process of a r=/sr= workflow. I'd see it
>>>as:
>>>
>>>1. All docs are authored with, edited in (with external editors or via
>>>the web interface, as the user prefers) and maintained in Zope.
>>>
>>
>> Right.
>>
>>
>>>2. When someone wants to edit something, a new version (in the Zope
>>>sense) is created. If more than one person creates a new version, the
>>>2nd through nth people are told of the other checkouts underway, but
>>>they too get their own version.
>>>
>>
>> I understand, and it does make sense, but this would really necessitate
>> that any given doc have an owner. Which is fine; that's kind of what I
>> was thinking. And I realise that having multiple check-outs of a
>> single doc isn't likely to be a huge problem. But if you've got a
>> single owner, it makes more sense (from a purely editorial perspective)
>> to limit things so that the doc can only be checked out by one person
>> at a time. If nothing else, it makes keeping track of the revision
>> history easier by several orders of magnitude.
>>
>>
>>>3. Versions marked "complete" trigger a review workflow task for the
>>>subscribed reviewer(s). Versions can be rejected (with a note to the
>>>submitter), sent back to the submitter for further work (with
>>>accompanying comments) or accepted. Upon acceptance, the new version is
>>>marked the current version in Zope and a task is created for the CVS
>>>publisher.
>>>
>>
>> I largely agree with this, but I'd like to see the work-flow a bit more
>> linear and focussed on local revisions ('diffs', I guess). It would
>> seem to make the whole process a bit easier. . . .
>>
>>
>>>4. On a (daily? twice daily? hourly? whatever) basis, the new versions
>>>of revised or added docs are checked into CVS by the zope server for
>>>inclusion in the source tree. No person checks docs into CVS.
>>>
>>
>> *This* last point makes an *awful* lot of sense to me, and takes care
>> of one of the issues with which I'd been wrestling. I kept thinking
>> CVS blame should, for any given doc, rest with one person -- /i.e./,
>> the person who checks the doc into the tree. This suggestion would
>> still keep (effective) CVS blame but automate the check-in process.
>> Makes sense to me.
>>
>>
>>>YMMV
>>>
>>
>> Always does. . . .
>>
>>
>>>--
>>>-sk
>>>
>
>
--
Mozilla end-user questions should be directed to:
snews://secnews.netscape.com:563/netscape.mozilla.user.general
snews://secnews.netscape.com:563/netscape.mozilla.user.win32
snews://secnews.netscape.com:563/netscape.mozilla.user.mac
snews://secnews.netscape.com:563/netscape.mozilla.user.unix
Note that you need to have SSL enabled and the port set to 563.
