Page 2 of 3

Posted: Mon Oct 28, 2002 1:56 am
by xitnalta
Ok, seems to take a bit longer. I will send in a preliminary version (heavily reformatted - but not too heavy 8) ) in the next few ... hours. ;) Also contains many corrections.

Posted: Mon Oct 28, 2002 2:39 am
by xitnalta
Ok - have fun, B@rt :)

Posted: Mon Oct 28, 2002 8:57 am
by S68
B@rt

looks a very good startup, sorry for answering late but I'm not online in weekends :)

I'll mail you LaTeX and POD entries later on today, and possibly some more stuff.

Stefano

Posted: Mon Oct 28, 2002 9:33 am
by Alvaro
well...
do you want to start new documentation in english?

so it means that Blender Foundation has not any GPL documentation in this moment...

and Blender Guides (Official and Game engine) won't never be GLP...

nice !!!! estupendo !!!!

how much time do we have to wait for :?:

Posted: Mon Oct 28, 2002 10:20 am
by k-fish
B@rt wrote:I have updated the document with a process flowchart that describes the CVS, Documentation Board, Authors and users. Please let me know what you think of it.
Ok. I have not yet read the whole document you wrote (wow!). But I looked at the flow chart, and must say that it looks very complete to me. Things like adding more content (blend files etc.) to the documentation can be sorted out later.

I'd definitely go for CVS to manage things, the split into board and authors is the basis for consistency I'd say.

Someone mentioned freezes, etc, to make translators happy - good point!

Thumbs up! This looks like a high quality proposal to start with, and should (hopefully) get things rolling sooner rather than later!

Karsten

Posted: Mon Oct 28, 2002 5:46 pm
by B@rt
Alvaro wrote:well...
do you want to start new documentation in english?

so it means that Blender Foundation has not any GPL documentation in this moment...

and Blender Guides (Official and Game engine) won't never be GLP...

nice !!!! estupendo !!!!

how much time do we have to wait for :?:
Hi,

I didn't say they will NEVER be GPL - in fact I'm hoping that they will. :-) I'm not writing these things to frustrate you, but rather to clarify the way things are...

B@rt

A note...

Posted: Mon Oct 28, 2002 5:48 pm
by B@rt
I'm on a company training for two days. The hotel where I am has internet access available, but I don't think I'll have much time to read this forum and answer my mail today and tomorrow. I'll work on it tomorrow night though - don't worry!

Of course I look forwards to hundreds of suggestions in my mailbox ;-)

Cya,

B@rt

Posted: Mon Oct 28, 2002 8:32 pm
by jasper
Great proposal, nice work B@rt.

I think docbook would be a good choice for tutorials/help pages, proposals :) etc.

I'm sure there are some decent programs out there that will do that job.

But I'm not sure if it would work for C code files & comments.

I recently discovered leo, 'the literate editor'
http://leo.sourceforge.net

see the website about what leo is. (i'm not gonna cp paste it)

The nice thing about Leo is that you could have a TreeNode containing the complete blender source, and that you can create other nodes with different views from the source, for example: bugs, todo, authors, dates, user-submissions, etc.

This would be an easy way to manage stuff like that, and because the leo file itself is xml,you can always use it for other purposes.

just an idea,

Jasper

Posted: Wed Oct 30, 2002 1:29 pm
by droddl
Heyho...

I followed the discussion about the Documentation now for about 4 days! And I have to say WOW! That's great!
@ B@rt: We just have to get to an and with all these proposals! IT's great work though! I think we have to organize now everything. Who gets involved and how? I can't wait to help, but I don't know how!

All I can say is WOW! Thanks Blender for making life so much better! :-)

bye

Posted: Wed Oct 30, 2002 1:29 pm
by droddl
Heyho...

I followed the discussion about the Documentation now for about 4 days! And I have to say WOW! That's great!
@ B@rt: We just have to get to an and with all these proposals! IT's great work though! I think we have to organize now everything. Who gets involved and how? I can't wait to help, but I don't know how!

All I can say is WOW! Thanks Blender for making life so much better! :-)

bye

Posted: Wed Oct 30, 2002 8:52 pm
by cessen
I like the idea of using Latex as the file format for documentation. It has several high-points (some of which are shared by othe formats):

1) It is a plain, ASCII text file.
2) It is easy to learn.
3) There are many tools for converting Latex files into other formats (such as HTML, PDF, and DVI).
4) The formatting-style of documents is dealt with independantly of the writing of their content. This means that the formatting-style can be written by the documentation board, and then all formatting is, effectively, automatically dealt with by Latex from then on.

Posted: Sun Nov 03, 2002 5:25 am
by matt_e
B@rt, I just had a look at your documentation proposal website. Depending on time and availability, I'd love to help with the 2d graphic design/layout/typography etc. of templates for documentation etc.

Posted: Wed Nov 06, 2002 6:48 am
by E2CMonkeyboy
WHATEVER you do, do NOT skip the little details on the "begining" tutorials - I can not tell you how many times I've pulled my hair out reading to press this button then that and wala - the finished product comes out and there were about 5 steps in between not "documented".
One of the worst thing that comes from programmers is - DOCumentation - so who ever writes the DOCS has to be a level removed from the program - beta testers and the like - now that the open source issue is over - we ALL are beta testers therefore potential DOC creators.
It is a potential AWSOME program to rival all others over time - it will take just that.

-The Flying Monkey

Posted: Wed Nov 06, 2002 9:55 pm
by Cyberdigitus
could'nt we use Doxygen as well, for developer docs? it's a system to extract documentation from code comments

Posted: Thu Nov 07, 2002 6:23 pm
by cessen
The documentation present in the code comments is ussually not sufficient as developer documentation. For instance, it doesn't give a very good over-view of the program architecture, etc.

Also, that is making the assumption that there are sufficient comments already in the code. ;)