[Bf-docboard] Welcome!

[Felix Rabe]

Hi Bart!

Some feedback...

On 11 Nov 2002 08:21:48 +0100
Bart Veldhuizen <bart@vrotvrot.com> wrote:

> The main issues are:
> 
> 1) Select a license. This is a subject that I know little about. Stefan
> and Ton are discussing this and Stefan is adapting the BSD license into
> a 'Blender Artistic License'. We'll hear more when Stefan returns.

As long as it will qualify as a free documentation license, I'm ok with
it.  If it is also compatible with some other key licenses (such as the
GNU FDL), I'll even be happy with it :o).

> 2) Define the 'products'. Stefan has written a detailed plan for this
> (and I'll leave it to him to present that here). The main products are:
> User documentation (manual,reference, tutorials), Programmer
> documentation (Code reference, architecture descriptions etc) and
> Metadocuments (License, Styleguide etc).

This is a good separation.

> 3) Choose a fileformat. DocBook/XML seems to be a good fileformat as
> it's text-based (--> nice for CVS), separates content from layout (-->
> nice for publication), has tools available for conversion into formats
> like HTML and PDF and is well documented. The drawback is that it's
> quite technical, and this might scare people away. We have proposed that
> people can deliver additions in other formats as well, and they will get
> translated to DocBook by a BDP volunteer.

I hope this won't be forever - I think this should be done through
automatic tools after a while.  Of course this only works if people
stick to the subset of their format that we'll define to be valid for
this...

> 4) Define a Table of Contents and try to boot up the project.

(See point 2.)  We should perhaps start with defining and writing the
metadocuments.  After all, they are the basis to work from for the other
'products'.

> I've
> written a proposal for this (along with some test content) in DocBook
> XML here: http://www.vrotvrot.com/BlenderDoc/BlenderManual.pdf.zip (also
> available as .gz). You can grab the sources from
> http://www.vrotvrot.com/BlenderDoc/BlenderManual.tar.gz . If you know
> DocBook, please have a look at it and see if what I did makes sense (I
> tried to keep Felix' remarks in mind ;-) If you have any changes or
> additions, please email me the changed files and I'll merge in the
> changes.

See above.  Maybe we also need some kind of "XML indent" (does that
exist?) to stick to a certain source format / and/or allow others to
edit XML in their preferred way.  (See forum discussions on astyle.)

> 5) Get a CVS account up and running on blender.org. Ton is talking to
> Hans about that now, but they're both very busy. Also, the upcoming
> SourceForge implementation seems to be eating a lot of their time. For
> the time I use my own CVS server. I won't give CVS accounts away because
> that would (as far as I know) require people to be able to log in to
> vrotvrot.com. If you have anything that you would like to commit just
> send it to me and I'll do it for you (and update the tarballs).

That's ok.  I just don't have any time now (see other msg.) to
contribute.

> What I would like to do until Stefan gets back is to work on the
> proposed Table of Contents and try to get that published at the end of
> this week. If you would like to experiment a bit by placing some
> sensible content into the framework, please go ahead and see how you
> like working with DocBook. Af the and of the week we can then post a
> call for participation and find volunteers to help us. 

I think this should rather be regarded as "experimental" at this point.
This experimental work can possibly be done in parallel with the work on
the metadocuments that define (as I understood it) in what way and under
what conditions people can participate.

> Please share your ideas on this approach with us.

There's not much going wrong from my point of view, so you had to ask a
second time for them ;).  Good work!

Felix