Wanted: better docs

General Forums Blender and CG Discussions
1

(I had originally started this as a response to a reference to an e-book in Guitar Solo (Gallery), but realized it didn’t belong there…)

Count me in for a copy of that e-book. :slight_smile:

If there is one thing, imho, that Blender needs more than just about anything, it would be “better documentation.” Nevermind that it is a hugely moving target, with all sorts of amazing features being added all the time, and nevermind also that CG in general is a mind-blowingly-large subject … it still needs high-quality documents that will help people move beyond “the basic monkey” without starting from scratch.

Granted, CG is a lot like swimming: you can’t just read a book about it, you gotta get in the water. And you won’t find any book on CG an “easy read.” But much of the material I’ve seen has fallen short of creating a bright, clear, easily-followed continuity from the basic to the advanced.

Still… every time I see a good CG book that discusses Maya or what-have-ye, I keep thinking that Blender represents an enormous un-tapped publishing opportunity.

I mean, think about it: if you want to learn 3D graphics and do video-oriented work in it, Blender is the most powerful and readily-available tool that you can get, to do that. Sure, it won’t be the only tool that you need to become familiar with if you intend to break in to studio work … but then again, if you’re signing on to a shop that does video, Blender just might well be the package you are expected to know! If you’re doing a contract for Hollywood, yeah, it might be Maya or Lightwave; but if it’s video (and a lot of work is done in video, especially HDTV), it is imho quite likely that Blender is going to now be the tool of choice.

Now mind you, I don’t mean this as any sort of negative comment about the fantastic work that’s now being done by The Blender Documentation Project! But why is the conventional publishing industry overlooking, as it were, this incredibly powerful open-source package?

2

[rant begin]

I agree, documentation is the weakest part of Blender, and whenever a “Blender vs XXX Software” thread pops up, the quality of the documentation is one thing that is rarely mentioned as a strength for those “bloated” packages.

Maya, Max, XSI, all have outstanding documentation/Tutorials that comes with the install (or is available as a seperate download).

The Fluid sim is a good example. Potentially very powerful, but basically undocumented. There have been a few threads here where we have struggled to figure out how to make obstacles / inflow etc work to produce a desired effect. (The summer of Docs touched on the Fluid Sim, but IMO that particular project focuses on too many things. A project on JUST the Fluid Sim would have been great).

Another example is the Nodes system. Little documentation on the wiki, only through experimentation and through other user’s feedback here, is it possible for a “node noobie” to figure out how to use them.

BugMan2000 is putting together a book on Character Animation which will be great, but even though he is a very experienced Blender user, he still needed to discuss and ask questions here about aspects of the program that SHOULD have been in the user manual.

It seems programmers just hate to document their work, apparently thinking that it should be “obvious” how to use a new fancy feature. This is true in other packages as well (another good example is Houdini, a tremendously powerful package, with weak-terse documentation)

So the only way documentation that gets developed is if a few clever people spend time on experimenting or user their innate talent to realize how the new whiz-bang feature works, and then spread the word through these forums.

I really get the distinct impression that many features are added to Blender by the programmers, just for the fun of programming them and seeing if they can get them to work. Spreading the word on HOW to use those features seems a low priority or something “someone else” will do.

[/end rant]

Mike

3

you can find almost everything you want at the blender wiki http://mediawiki.blender.org

4

Not really, the documentation is incomplete and not written to the standards users of the big expensive professional products would expect.

Blender needs real work to be undertaken on its documentation. It needs to integrate better into the available documentation. There needs to be soem sort of "How do I… " cheat sheets for common topics, and more than anything else Blender needs a book that can help newbies find their way, preferably one with a narrative of sorts running through it, with tutorials that build on each other and the like.

5

The exception being some of the projects of the Summer of Docs, … which only happened when people were paid to do it.

Mike

6

Doscumentation on every feature in Blender can be found, the problem is that it’s not all in one place. The easiest way to find a feature is to do a search. If you don’t find it in the search, you ask here, and at some point an experienced user will answer your question.

7

I’ve come to Blender as a user (and teacher) of Maya, Cinema 4D, and Lightwave. I’ve become very fond of Blender despite the fact that its documentation is thin, primarily because I love how pared-down it is, at least in the core application.

If I can be heretical here for a moment, Cinema 4D was my first heavyweight 3D application, for the reason that, once you “got” the way the program thought of the work process, you could anticipate how to do almost anything within the program. Documentation was largely unnecessary, and when it comes to published, paper-printed versions of documentation, I don’t know of any other major program besides Blender where the documentation is as sparse and out-of-date as that for Cinema 4D. Still, I can’t recall how many times I was able to just do something I’d never done with Cinema before, just because I was able to predict, from previous use, exactly how the programmers would allow you to access or tweak a particular function. This is similar to the amazing cross-functionality of the Adobe interface, which allows someone familiar with Photoshop to actually get work done with InDesign or GoLive without ever touching any documentation. This is most emphatically not an experience I’ve had very often with Blender. I’ve had it a couple of times, but far, far too rarely. It’s also something that Cinema 4D, in bringing in such 3rd party additions as Pyrocluster (voxels) and Thinking Particles has also jettisoned, dramatically lowering my interest, and faith, in the application. My thinking along these lines has been, “Well, if it’s going to be a pain, I’d rather use a free program than pay through the nose for every new feature and dot-upgrade.”

My take on this argument is that Blender would need far less documentation if there were some way to ensure that all the elements of the program adhered to the same philosophy and operated the same way, regardless of author or purpose. I realize that this is difficult to do, and may even be against the core programming philosophies of the primary Blender contributors, but I hope, as a determined and eager Blender adopter, that the programmers would take more account of the final user and less of the elegance of the underlying structure in their grouping of functions and processes.

As it is, every new Blender function (and with each release, several of the old) requires a new explanation of the vocabulary, the use, and the workflow of every process. There’s no way for the documentation to keep up. I’m of the opinion that, aside from the renderer, every aspect of Blender is now world-class, and I’d be perfectly happy to wait an extra six months to a year while each and every new feature was trimmed and altered to be intuitively clear from its first appearance. Yes, trimmed, yes, altered, and yes, dumbed down and made slower.The hours spent learning a totally new interface are always irretrievably lost. No amount of efficiency will ever make up for them , especially as that efficiency will, more than likely, be jettisoned with the next update.

Blender has tons of wonderful features that I only wish other programs had, but they need to be forced in to a consistent interface, where their application is intuitively obvious to the user. I would say that Photoshop would be an example of the ideal, in that it takes less than a week to learn, but many, many years to master.

8

there is centralised blender documentation but it isnt updated with the latest features such as the node etc. if you want “How do I…” cheat sheets, search/look in the tutorials section or just read the description on how to use particular features on the www.blender.org website.

9

My take on this argument is that Blender would need far less documentation if there were some way to ensure that all the elements of the program adhered to the same philosophy and operated the same way, regardless of author or purpose. I realize that this is difficult to do, and may even be against the core programming philosophies of the primary Blender contributors, but I hope, as a determined and eager Blender adopter, that the programmers would take more account of the final user and less of the elegance of the underlying structure in their grouping of functions and processes.

As it is, every new Blender function (and with each release, several of the old) requires a new explanation of the vocabulary, the use, and the workflow of every process. There’s no way for the documentation to keep up. I’m of the opinion that, aside from the renderer, every aspect of Blender is now world-class, and I’d be perfectly happy to wait an extra six months to a year while each and every new feature was trimmed and altered to be intuitively clear from its first appearance. Yes, trimmed, yes, altered, and yes, dumbed down and made slower.The hours spent learning a totally new interface are always irretrievably lost. No amount of efficiency will ever make up for them , especially as that efficiency will, more than likely, be jettisoned with the next update.

oh god, where to begin? i disagree with everything you said. blender is not built for ease of learning, it is designed for efficiency. the blender interface is highly consistent, it is just the workflow you are having trouble with.

i would point out that a violin is hard to learn as well, but i don’t hear anyone complaining about the interface.

The hours spent learning a totally new interface are always irretrievably lost. No amount of efficiency will ever make up for them , especially as that efficiency will, more than likely, be jettisoned with the next update.
i find this statement in particular, ridiculous. i lived through many blender upgrades - i’m using an experimental build right now - and have never experienced a jettisoning of anything. what are you talking about?

10

I agree with troutmask.
And documentation these days is pretty solid, but the problem is that there is also alot of bad documentation, and you have to sift through the goood and the bad.

11

I doubt the programmers have the time to bleed out even more work. I bet they work for the thrills and chills of competing with and blowing away the competition’s capabilities. The record keeping necessary for a tech manual probably just doesn’t have the same fiery appeal. But as we have already seen with the Summer of Documentation, a reward of food and drink makes all the difference.
Would it be difficult, for someone who knows how to pitch such things, to suggest to a commercial company that they take up the torch of documentation? With Elephants Dream pushing blender even closer to the mainstream world, would it be all that hard to convince a publisher that they could make a profit off of commissioning intermediate blender manuals? Especialy since the greater public is likely more interested in 3D as a hobby than an occupation, with a deep manual to ease the learning curve, full featured blender with a pricetag of 0 is an ideal starting point for the casual beginner.

I see an untapped potential here.

12

There are a couple of problems that I have identified in Blender’s documentation system:

  1. There’s documentation that is split between blender.org and the wiki. There’s duplicate information in both places such as manual, FAQ or release notes.

To counter this problem, the sites needs to be integrated better. Or perhaps they should be separated instead? Should developers have their own dedicated site for example?

  1. We have got a lot of documentation that is fragmented. By this I mean tutorials found here in the forum, on the users sites and many other places.

There’s no a clear procedure available to migrate documentation to the wiki. Also the question remains whether the wiki should be a hub of information or should it have a more limited role.

The main problem of fragmented information is perhaps familiar to all: “404: Page Not Found” error. Also the fact that it may be hard to find could be in issue. Of course it is rare that information can be updated to reflect current version later unless it is in wiki or similar system. Wiki would make these problems obsolete.

  1. There are empty spots found in the wiki documentation yet no description of what they should exactly contain exists. It is unfair towards the authors for them to have to guess what they should write.

  2. The documentation is outdated. This is consequence from the furious pace of development.

Possible solution would be to have some sort of “TODO” list created. At each commit to Blender’s source a note about it would be added on TODO. This would help the effort of those who document these changes to the wiki.

The concept of TODO list could further be enhanced. It could also help in problem described in 3.

  1. There are no enough wiki contributors. This may be due to things discussed above. Attaining editing rights and learning wiki syntax may be an obstacle. It is easy to say that documentation is bad and not to do anything about it.

Currently we are organizing a meeting for people interesting in developing the wiki. A list of issues can be found at http://mediawiki.blender.org/index.php/User:BeBraw/WikipeopleMeeting. You are encouraged to discuss the issues and also to give feedback. We are discussing about when it should be arranged today at the coder meeting.

13

Possible solution would be to have some sort of “TODO” list created. At each commit to Blender’s source a note about it would be added on TODO. This would help the effort of those who document these changes to the wiki.

with every blender release there is a write up on blender.org about the new features. this write up simply needs to be copied over to the wiki, and can, with minimal effort, be fleshed out.

14

I worked in a firm which made handbooks for electronic devices. There I learned, that the tecnicans are able to produce “tecnical” informations, but it needs a “author or writer” to translate these tecnical informations into a user friendly and acceptable form. I know I´m dreaming, but the best people for writing Documentations should be the artists, allways in close cooperation with the tecnicans. Not every songwriter is the best interpret of his own songs :slight_smile:

Dada