[Zope3-dev] Zope 3 Developer's Book Development Process

[Stephan Richter]

Hello everyone,

recently people showed a great interest in updating the Zope 3 Book. I totally 
admit that it is not that obvious on how to help out, but this is a bit 
intentionally, since I have to keep a high quality for it. The following text 
will describe the possible levels of involvement. It is just a rough draft, 
but should provide enough insights to get started. E-mail me, if you have 
questions or problems.

=======================================
Zope 3 Developer's Book Writing Process
=======================================

The Zope 3 book is a faiirly large project by itself. It is necessary to keep
it in a high-quality state at any time. The master copy of the book is located
in a special CVS repository at Zope Corporation in LaTeX format.

Level 1 (Casual Reader)
-----------------------

Read the book chapter by chapter and send me a mail of what you think about
it. Here I am specifically looking for *constructive* feedback about the text
itself:

  - Did you have to read certain sentences/paragraphs/section more than once?
    Were they too dense?

  - Did you get bored reading certain parts? Were they too information thin?

  - I am not a native English speaker. How is the the grammar/verbalism of the
    text from technical point of view?

  - I write intentionally in an "instructional style". I always had good
    feedback from fellow students about this style. What do you think? Do you
    like/dislike it?

Of course, specific examples of criticized text will always be more helpful
too. At this stage, it is still possible to make changes to any of the above
points as I plan to have at least 1.5 complete revisions of the book before
sending it for editing to the publisher.


Level 2 (Interested Reader)
---------------------------

While you are reading, make notes about specific errors, which include,
spelling, grammer and verbalism. I also had some very good feedback from
people about sentences or paragraphs that did not make much sense, since I was
sloppy writing them.

You can send in the comments the following ways:

  - E-mail: Send me an E-mail with the corrections. The E-mail could have the
    following form::

      Chapter X

        Section Y, para 1, line 2: typo 'have' - Then you habe to insert ...

        Section Z, para 3, sentence 2: unclear, please rephrase

    Of course you can use any abbreviations you wish as long as I understand
    them. 

    If you have changes to the code of a particular example, you can also send
    me patches.

  - Wiki: You can directly edit the Wiki, since I get the diffs as an
    E-mail. Note though that for some reason if you edit too much at once in a
    Wiki, the diff mechanism gets confused and does not produce usable
    diffs. At this point your changes will be lost, since I have no efficient
    way of getting to your changes. 

    Further, the Wiki Pages will be more and more auto-generated, which means
    that markup changes will be reset, once I update the Wiki
    version. Therefore, if you want to make structural changes, please do so
    in a different editing session than textual changes.


Level 3 (Editor)
----------------

The entrance level for the editor is intentionally much higher, since s/he
will be able to modify the master copy without my approval or revision. That
means that the editor needs to take great care to keep consistent.

While the Content Component recipes are the best ones to start reading, they
are the worst ones to start editing, because if you make a change in the first
recipe (step 1), you have to update all other 12 steps exactely the same way
as to not confuse the reader.

Make sure to always keep the code and the text in sync.

Here are the steps required to get involved:

  - Sign a contributor agreement and get CVS access.

  - Ask Jim for priviledges to access the book repository.

  - Check out the repository::

    cvs -d :ext:<username>@cvs.zope.org/cvs-special-projects checkout 
zope3book

  - To compile the book into a PDF, you have to have LateX installed. You can
    create the PDF by typing just 'make' in the zope3book directory.

  - To create new STX files, you pyLaTeX installed. Just search the Web for
    it. Once it is installed, you can just type 'make all-stx' or::

      python latex2stx.py dir/file.tex

Since this repository is not setup with E-mail notifications, please E-mail me
when you changed a chapter. I can then use the CVS diff facilities to see what
you did. Also, do not check in any generated file. The .cvsignore file does
not work for this repository, so that I was unable so far to automatically let
the system ignore generated files.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training