Re: documentation and the book module (was reflections onthe Drupal 4.3.0 battle)

On Wed, 22 Oct 2003, Dries Buytaert wrote:

> On Wed, 22 Oct 2003, Peter VanDijck wrote:
> > It seems to me we have 2 audiences:
> > - (some) developers want to write docs using CVS and some hardcore doc
> > format.
> > - (some) less techie contributors want to contribute to the
> > documentation.
> >
> > Both have good arguments.
>
> And what if we'd make a small module that loads a LaTeX or Docbook
> source file, presents it in a textarea and lets you update it?  You

I don't know about Docbook, but LaTeX is usually quite scary for people
not used to it. BTW: IIRC there is a Docbook format that lets you
generate LaTeX output.

> would not be able to preview your changes but once you click submit,
> a patch is generated (against the source file) and send out to the
> drupal-user mailing list for people to pick up, test, and -
> eventually - commit to CVS.

I would suggest a slightly different approach:

- Maintain the Docs in some format in CVS.
- If update through the web is desired, generate HTML from the Source
  (ususally easy).
- Generate a diff against that HTML as you proposed.
- Let somebody else put the changes into CVS.

The problem would be that the person who puts the patches into CVS would
need to convert them to LaTeX or whatever. But this is a much smaller
problem than presenting non-LaTeX users with the task to edit LaTeX
sources.

> > My pov is that editing and writing is indeed a lot more work than
> > generating an index and such, so we should optimize for that.
>
> That is exactly why I suggest to use LaTeX or Docbook; they enforce
> consistency and take over nearly all visual aspects.  Using these
> tools, the writer can focus on writing text.  They are specifically
> designed for documentation/book writing.

That is correct, although you can spend a lot of time with making your
results perfect. (Eg: in German texts you have to remove a lot of
ligatures by hand (or by a programm that I wrote :)).

> Anyway, I give this discussion some more thought.  In the mean time,
> I rest my case; no significant documentation improvements are going
> to happen unless someone puts a lot of time and energy in improving
> the book module.

I think that using the limited workflow possibilities that we
have (queue.module) would help. It should not be available to the
public, but to those who have the "admin node" permission now. From
several comments I infer that it is not available on Drupal.org.

By using queue.module, the people who update/commit book nodes would at
least get some feedback on what is happening to their node.

> Implementing such improvements is not on my radar of current
> priorities because I know that the result will never match that of
> the manuals on my book shelves -- or that of a carefully crafted PDF
> file.

You always need to put in some work by hand. This is what I learned from
a addressbook project. I thought "this is going to be easy, it is all in
the database". It wasn't.

> Hopefully someone will stand up and proof me wrong; either with
> code, significant documentation updates or a better idea.

I've never been good with writing docs, but I might have some ideas (and
even some code: workflow.module) for better workflow.

Cheers,
	Gerhard

-- 
[ Drupal user list | http://list.drupal.org/ ]
[ http://lists.drupal.org/options/drupal-user/gcpdu-drupal-user%40gmane.org ]