A proposal..

xitnalta · Post by **xitnalta** » Mon Oct 28, 2002 1:56 am

Ok, seems to take a bit longer. I will send in a preliminary version (heavily reformatted - but not too heavy

) in the next few ... hours.

Also contains many corrections.

xitnalta · Post by **xitnalta** » Mon Oct 28, 2002 2:39 am

Ok - have fun, B@rt

S68 · Post by **S68** » Mon Oct 28, 2002 8:57 am

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

Alvaro · Post by **Alvaro** » Mon Oct 28, 2002 9:33 am

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

k-fish · Post by **k-fish** » Mon Oct 28, 2002 10:20 am

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

B@rt · Post by **B@rt** » Mon Oct 28, 2002 5:46 pm

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

B@rt · Post by **B@rt** » Mon Oct 28, 2002 5:48 pm

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

jasper · Post by **jasper** » Mon Oct 28, 2002 8:32 pm

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

droddl · Post by **droddl** » Wed Oct 30, 2002 1:29 pm

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

droddl · Post by **droddl** » Wed Oct 30, 2002 1:29 pm

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

cessen · Post by **cessen** » Wed Oct 30, 2002 8:52 pm

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.

matt_e · Post by **matt_e** » Sun Nov 03, 2002 5:25 am

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.

E2CMonkeyboy · Post by **E2CMonkeyboy** » Wed Nov 06, 2002 6:48 am

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

Cyberdigitus · Post by **Cyberdigitus** » Wed Nov 06, 2002 9:55 pm

could'nt we use Doxygen as well, for developer docs? it's a system to extract documentation from code comments

cessen · Post by **cessen** » Thu Nov 07, 2002 6:23 pm

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.

Blender.org

A proposal..

A note...