NaN documentation database + future

Blender documentation projects, tutorials, translation, learning & teaching Blender

Moderators: jesterKing, stiv

ton
Site Admin
Posts: 525
Joined: Wed Oct 16, 2002 12:13 am
Contact:

NaN documentation database + future

Postby ton » Sat Oct 19, 2002 2:49 pm

We've got a lot of material to publish. There are three issues related to it:

1. The proper license
2. How to (re-)organize this
3. How to continue after, setting up an 'official' documentation project

Proposal:

1. License
I find the GNU FDL hard to grasp... we might move to it in the future, but I need a better understanding of it first. We will also publish/produce more than just documentation... a lot of other content is part of it too.
Therefore, my idea is to put the NaN docs online under a MIT license, which allows maximum freedom (including moving to a different license later):

===============================================
Start Of Blender Foundation Content License
===============================================

Copyright (c) 2002 NaN Holding, Amsterdam the Netherlands
Copyright (c) <year> <copyright holders>

Permission is hereby granted, free of charge, to any person obtaining a copy of this documention and associated files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

===============================================
End Of Blender Foundation Content License
===============================================

2. Re-organize it
I want to put this all available at blender.org, just as a database. I then like to appoint a small team, to go over it, clean stuff up, turn it into a proper organisation, throw stuff away...
This team then can also propose the next stage, in discussion here with other interested people:

3. Documentation project
Meaning: setting up a system which allows a proper organisation of (all) Blender projects going on at blender.org.
I prefer to appoint a small team of moderators for this, who will coordinate and organize the much larger group of volunteers working at it.

'2' and '3' are related... but also don't overlap completely. For feasiblity of this project, it might be possible that the old (but reorganized) NaN database will remain available separate from the official Documention Project. Just out of practical and historic reasons...

---

Any feedback? Volunteers?
Last edited by ton on Sat Oct 26, 2002 5:07 pm, edited 1 time in total.

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Re: NaN documentation database + future

Postby xitnalta » Sat Oct 19, 2002 6:00 pm

ton wrote:Any feedback? Volunteers?


Feedback: good proposal. Maybe before actually trying to understand the GNU FDL, you should define what you expect the license to do. For example, do we need the feature of the GNU FDL to define invariant sections? Do you want a copyleft license that prevents the freely available docs from being used in proprietary works (such as traditional, non-free books)? This is something that maybe can't be discussed enough. I would be relieved somewhat if I knew that there was an experienced lawyer on your side. (And who (nickname?) it is.)

Volunteers: I will do what I can, but only with a warranty disclaimer - school is starting again for me this monday. But, on the other hand, it converts some of my daily 12+ hours of sleep into productive activity, which might make up for the more-stuff-to-do thing. -> Count me in!
Felix

voidptr
Posts: 21
Joined: Mon Oct 14, 2002 2:26 am

Postby voidptr » Sat Oct 19, 2002 9:50 pm

I would be willing to helpl. I've been doing some local code documenting & was thinking about writing some coding tutorials for GameDev magazine (once the source solidifies). I'm really interested in seeing Blender turn into a platform, instead of a program.

For the reoganization part of the task. What are you speaking of? The code or the documents? How would the documents be placed into a database? What exactly were you thinking of?

In http://www.blender.org/modules.php?op=modload&name=phpBB2&file=viewtopic&t=170 H_xNaN has suggested using Tinderbox (and everything in it) this would be a good tool in my opinion.

As for documentation tools? I've seen many good starts in all the posts. Doxygen, DocBook, plus others. For large scale documentation systems OpenOffice has a very good setup, maybe we could borrow there's? Perhaps we could use this as a start point?

A documentation standard needs to be in place for new code. And a list of cleanup points should be in place to stop duplication of effort. But I imagine the coding forum has part of this in hand already :)

So many questions so few answers. Let me know if I can help.
voidptr - dean_@_voidptr_dot_com

Goofster
Posts: 137
Joined: Mon Oct 14, 2002 12:26 pm

Postby Goofster » Sat Oct 19, 2002 10:59 pm

well, you alreayd know I'm all in for it :D

at the moment i'm very enthousiastic about reorganizing documentation:

1) as long as it's not code documentation (EEK! coding)

2) I havn't seen the actual documentation yet, so my mind could change if I see it :)

to quote mister Jackson: "just call my naaaaaaame and I'll be theeeeeeeeeere"

Roel Spruit

hawksmoor
Posts: 12
Joined: Mon Oct 14, 2002 8:25 am
Location: Italy

translating docs

Postby hawksmoor » Sun Oct 20, 2002 3:41 pm

hi, Ton

I'm very pleased that we can now have the opportunity to have some organized documentation (at least, in the near future) on blender.
I'm not a developer, just a simple user, mind you, and I have a full time job so I haven't much time (even less, 'cause my three years old daughter is a little daredevil) but I volunteer on doing some work: I have just begun translating in italian one of the tutorial posted on IngieBee site (with her consent, of course) and am planning on doing it on a regular basis on blender.it, since english is not a problem for me.
If this could be of some help you can count me in, although on my spare time.

Since then, long live and prosper

Andrea

kino
Posts: 94
Joined: Sun Oct 13, 2002 7:37 pm

Postby kino » Sun Oct 20, 2002 7:02 pm

Hi Ton

How about localization? by blender.org?

edited : sorry, stupid question

i'm disponible for translation, italian too



Kino

sofort99
Posts: 4
Joined: Sun Oct 20, 2002 7:02 pm

Postby sofort99 » Sun Oct 20, 2002 10:51 pm

Hey ton!

I was wondering if there could be a Re-organizeation for a users manual that was centered more around what you needed to do instead of in a book form?

What I mean is most users manuals are like this..

TOC:

BODY:

CONCLUSION:

INDEX:

instead of..

What do you need to know?

modeling--
................|_primative
................|_latic
................|_subsurf
..............................|_edit subsurf
..............................|_paint subsurf
..............................|_etc
.....................................|_etc..etc...what I need to know
materials--
rendering--

Unfortunatly, I understand what I mean exactly :roll: , but I am not sure if I can explain it so anyone else can. But the end result is the doc laid out in a search tree to make it easier to find specific info on how to do what you are wanting to do even if you don't know what it would be called, or where it would be, alphabetized in a book.

IngieBee
Posts: 120
Joined: Sun Oct 13, 2002 8:26 pm
Contact:

Postby IngieBee » Mon Oct 21, 2002 5:49 am

Well it looks like it's starting to come together. I guess I'll be sending Raymond flowers and chocolates :P :oops: He's my new best friend (seeing as he's gonna do the VR stuff :D )

Hi Raymond!!! What kind a chocolates do you like, or how about some good mexican teqila??? Hee hee hee. Anything for you my best buddy!

Love Ingie

pato
Posts: 18
Joined: Wed Oct 16, 2002 5:50 pm

Postby pato » Mon Oct 21, 2002 5:17 pm

This sounds great! Count me in to help!

I've been longing to see Blender come shipped with high quality documentation! Hopefully with some well done docs we won't see so many posts that say "I didn't know Blender could do that!" or "I tried to use Blender but I couldn't figure it out." :-) Let's get this party started! Cheers all!

-Jason <Pato>

gpg
Posts: 2
Joined: Mon Oct 21, 2002 10:24 pm

Postby gpg » Mon Oct 21, 2002 11:26 pm

Any feedback? Volunteers?

OK

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Postby xitnalta » Tue Oct 22, 2002 1:58 am

sofort99 wrote:instead of..

What do you need to know?

modeling--
................|_primative
................|_latic
................|_subsurf
..............................|_edit subsurf
..............................|_paint subsurf
..............................|_etc
.....................................|_etc..etc...what I need to know
materials--
rendering--

As I see it, it is "only" a good proposal of a table of contents for a user guide. But I think this sounds too great in theory to have no problems with detail issues that arise when you actually try to implement that.

But try it! For the technical stuff on blender.org it will probably be more difficult to try out your idea.
Felix

leinad13
Posts: 216
Joined: Wed Oct 16, 2002 5:35 pm

Postby leinad13 » Tue Oct 22, 2002 1:05 pm

I volunteer to help re-organize or create documentation.

Anything i can do to help just mail me.

-------------
L!13

jeotero
Posts: 107
Joined: Wed Oct 16, 2002 5:31 am

Postby jeotero » Wed Oct 23, 2002 3:16 am

i could help with graphic design for the documentation

rontarrant
Posts: 6
Joined: Wed Oct 23, 2002 12:28 pm

Documentation Help

Postby rontarrant » Wed Oct 23, 2002 1:43 pm

Hi all,

I'd like to volunteer to help with the Blender docs.

In my last two jobs my duties included:
1) writing docs for new software,
2) editing content for brochures, web pages, CEO coorespondence, white papers, and software manuals,
3) hand-coding HTML
4) and graphic design/layout.

I'm a trained artist (degree in Fine Arts) and I've been a writer for over twenty years. I'm also a published author (see: actiontales.com and/or look up "Ron Tarrant" on imdb.com). I can bring the following skills to the documentation project:

- grammar (English only, I'm afraid)
- organizational skills
- HTML coding
- graphic design/layout
- editing

I am willing to do whatever needs doing. I can dedicate roughly seven to ten hours per week to this project as long as the rest of my life doesn't become overwhelming, which is not likely in the next few months.

In school during the late 1980's, I studied 3D modeling and animation using Sculpt-Animate 4D. I also studied Maya for a while as well as most other 3D applications for MS Windows and Linux/FreeBSD. I've been playing with Blender off and on since version 1.5 or so, but I've never really gone very far with it. Even though I lack a good overall understanding of Blender, I know 3D software in general. I also find it easy to remember what it was like to sit down with a new software package for the first time and that is reflected in my documentation technique.

One suggestion I'd like to make is that the doc base be done in HTML, preferably hand-coded. This would allow everyone working on the project to use their platform of choice, for one thing. For another, tools are available to convert HTML into just about any type of 'delivery' format (PDF, Windows Help, etc.) even if the conversion involves more than one step. I would have suggested SGML as a base format, but conversion tools aren't available for the Windows environment, at least I've never seen any.

Using the DIV tag in HTML, just about any layout is possible and close consistency is maintained across platforms. Tag usage is a bit strict and handling DIVs at the coding level can be a pain sometimes. I think it's worth the extra effort because an HTML document done this way will look almost identical in all recent versions IE, Netscape, and Mozilla.

Just a suggestion. Do whatever you want with it. :-)

Please let me know how I can help.

-Ron T.

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Re: Documentation Help

Postby xitnalta » Thu Oct 24, 2002 12:49 am

rontarrant wrote:Hi all,

Hi Ron!

That was actually exactly the way people should promote themselves into any moderatoring boards here - by saying what they can do and then, to prove that they know what they're talking of, giving an opinion about it. Well done!

But that doesn't mean I automatically also agree with you. ;)

rontarrant wrote:One suggestion I'd like to make is that the doc base be done in HTML, preferably hand-coded. This would allow everyone working on the project to use their platform of choice, for one thing. For another, tools are available to convert HTML into just about any type of 'delivery' format (PDF, Windows Help, etc.) even if the conversion involves more than one step. I would have suggested SGML as a base format, but conversion tools aren't available for the Windows environment, at least I've never seen any.

I'm totally against it. Not because I would have more experience than you (I only live since '85 and started programming with 8 years, so I'm now only about 9 years "married" to computers ;) ), but because I know (not only) HTML fairly well to know that it is not the best (and, I would argue, also not even a good) solution to this.

But please just join us by contributing to this thread about documentation formats (that I had to flame a bit, sorry, but you'll find out why). It contains (almost) all of my arguments for DocBook XML and quite a detailed description of what it is. (I think you meant DocBook SGML by SGML, which (SGML) in my eyes is just the complicated, big, and old brother of XML. Correct me if I'm having a completely wrong assumption about these two here. I only know XML (+its spec) fairly well.)

You don't actually need to install and/or write DocBook XML locally at your machine to help authoring documentation if DocBook XML is used as the central format. The processing (converting author documents to DocBook XML, and generation of other formats) can be done centrally somewhere on blender.org (or by The Documentation Staff, which seems to include me :roll:), and I envision that for writing Blender documentation, people should be able to contribute in the format that suits them best (and/or is easiest to check for errors in their work environment).

To join, just start discussing, contribute your ideas, and then feel free to work on tasks that show up or you see need for doing. Currently, we're mainly discussing, but things sort out fairly quick that way.

Stay tuned and feel welcome!
Felix


Return to “Documentation & Education”

Who is online

Users browsing this forum: No registered users and 0 guests