[Bf-docboard] Welcome!

[Roel Spruit]

ok, finally have some time to get some stuff done. here are my views on
B@rt's issues:

----- Original Message -----
From: "Bart Veldhuizen" <bart@vrotvrot.com>
To: <bf-docboard@blender.org>
Sent: Monday, November 11, 2002 8:21 AM
Subject: [Bf-docboard] Welcome!


> Hi,
>
> welcome to the Blender Documentation Project (BDP) maillist. As Ton
> wrote yesterday, the Foundation is working hard to install a SourceForge
> style project environment on blender.org. In the mean time we can use
> this maillist to get the BDP going.
>
> Stefan, Ton and I have already been discussing some issues.
> Unfortunately, Stefan is out of town & offline until Friday, but I think
> we can start thinking about some things before he returns.
>
> 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.

I'm not into licenses and stuff, so I can only comment on this if I see
stefan's license. I'll probably ask icky license-newbie questions then, but
maybe Ii'll even have a good point (though the chances of that are very VERY
slim :)


> 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).

Looks ok to me. one small thing:
maybe it's a good idea to have "General blender info" as a group too. maybe
it's better if the website boys do this, but maybe it would be nice to have
some general document that explains what blender is, what you can do with it
etc.
though I guess it's possible to think of that as User Documentation.

> 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.

>From what I've heard of docbook/XML it seems very nice indeed. other then
the point you already made about the technical nature of Docbook/XML I have
no objections to it. Translation from other format's shouldn;t be too hard
for experienced Docbook people (wich I hope I will be if I get the bloody
docbook enviroment working :)

> 4) Define a Table of Contents and try to boot up the project. 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.

looks like a viable manual setup. the quickstart thing is a must. no one
wants to dig through a manual first and then make something.

> 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).

woohoo! cvs! something I could actually use on my box :)

> 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.

you mean publish the table of contents from your manual test on .org? 2
things:

1) publishing it is a good way to make sure we don;t leave anything out,
but...
2) publishing it this early will probably unleash a whoooooooole lot of
people at us that go: "how's the manual coming? is it done yet?"
(and we CJ-people all know that's ok for a week or so, but after a few
months it starts to get a bit annoying :)

> Please share your ideas on this approach with us.

voila

> Cheers,

Proost,

> Bart

Roel

>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard@blender.org
> http://www.blender.org/mailman/listinfo/bf-docboard
>