A discussion on Blender documentation

General Forums Blender Development Discussion
1

MODERATOR EDIT: This thread was split from the Cycles Development Updates thread. Please read through these posts before responding… this OP isn’t necessarily the core of the discussion.

I don’t think it is wise to waste time learning when you could be creating.

Software builders should look at driving rules and signs. Or even flying rules after all it is 3D.
Look at its appeal, in whole world with many cultures there haven’t been any real resistance against it. Why? it is simple, make general sense, use already existing concepts/language.

Imagine designing a node system with left, right, up, down, speed, acceleration, follow, instead of “quartenion” etc…

2

I encourage you actually look into the rules for flying before making generalizations about how straightforward they are. Pilots are highly trained with some very specific jargon. It’s not as easy as it seems in a videogame.

If you know a simple way to have multiple axis rotations without gimbal lock, please propose it. If you don’t understand the limitations that more technically powerful tools overcome, you are in no position to be proposing improvements.

3 Likes
3

I am severely put off by the lack of examples in the blender doc. Often times you cannot obtain instructions for actually using those nodes. It reads more like a technical specification than a user manual.

5 Likes
4

There is nothing wrong with sending the user to the manual for things that really require a longer explanation.

This is not the case here.

Also, insulting people, saying they’re illiterate, not cool.

1 Like
5

Same here. I tried forever to learn various programming languages and never got anywhere with any of them, then I discovered the PHP manual website was overflowing with both official examples and scores of user submitted examples in the comments.

1 Like
6

Absolutely. The manual just barely answers ‘What is this?’, and almost never answers ‘What is this for?’. But we’re sort of running off topic here, this pertains to all of blender, not just Cycles.

1 Like
7

That’s not even vaguely what I said.

8

Oh. Well what did you mean to say?

9

I meant to say exactly what I said. You just decided not to read all the words. Or perhaps not look up the term you didn’t understand. Very meta.

1 Like
10

Sorry, you’re not making any sense to me.

11

Just like Blender itself, Blender’s documentation is editable and improvable by anyone. Even better, this is exactly the kind of thing that “normal” artists can help with contributing to Blender’s development. Think the documentation is lacking? That’s a prime opportunity to step up and help out.

21 Likes
12

To contribute to the documentation, you are asking a person to be knowledgeable in the content that’s being written. This is a given.

You are also asking the person to write restructured text and not wysiwyg. You are asking the person to build a local version of the documentation, which means setting up build environment. You are asking the person to be familiar with an outdated source control software (svn). You are asking the person to submit patches and get it reviewed like code patches.

A normal artist doesn’t do any of the above. You are basically asking half a Pablo dobarro, just for the documentation.

A video on YouTube is way easier. The documentation is destined to rot.

4 Likes
13

I wonder if quality of manual would’ve improved if devs switched to a wikipedia engine wiki… Wysiwyg editor and ability to contribute without dev account would make it much easier to contribute even if in theory it also makes it easier to vandalize.

I once had a impulse to copy or remake pictures from old addon homepage to current manual looptools page but gave up because I didn’t have dev account and was too lazy to figure out formatting. Right now manual page is completely useless for me since it’s just wall of text without any examples.

6 Likes
14

I’d say a video is harder to produce than a text edit, with equal effort spend I’d guess the rot on outdated youtube video’s is worse than on outdated documentation.

Also it’s likely a personal preference, but i’d take written documentation over “EYYYYYYYYyyyyyy! this is your boy sheepfondler37 and today we’re gonna make a chicken in blender, be sure to hit like and subscribe, but first a word from our sponsors, if you’re looking to build a website, give circle earth a try!”

16 Likes
15

The reason why videos now have so many sponsor segments and Patreon appeals is because Google has made it virtually impossible to make a living from ads. I speculate the company would rather not share its revenue at all if it got to where it would not have much negative impact on Youtube’s traffic.

In addition, I also agree that text and images are far easier to keep current than a video, as you can’t just update a portion of a video (it has to be completely reshot to avoid jarring transitions).

1 Like
16

If they could add some https://disqus.com/comments plugins on every documentation page we could have conversations at the bottom of the page and eventually a developer can uplift some of that information into the actual documentation.

1 Like
17

Using proprietary commenting software is just asking backslash. Nor do I think ton would approve using one in their infrastructure

1 Like
18

Fine. Someone else clone the documentation elsewhere and put disqus on it and then eventually a few volunteers can learn svn and the docmentation system and add info from the best disqus comments to the real docs.

19

@thinsoldier
You are suggesting to fork the documentation just to add a commenting system and expecting people to work on it?

On top of that expecting people to learn svn which is likely the biggest obstacle of all?

The forum is as dead as it could get. A fork with comments won’t help.

I am not learning svn just to write a few words.

The git migration task has been abandoned for one and half years.

Blender itself already migrate to git and there is a github mirror to it. They could have done the same for the documentation repo but didn’t. Which should be pretty telling the bf’s priority on the user manual.

Just look at godot’s documentation on github: https://github.com/godotengine/godot-docs/issues

The “Edit page” at the botton of every documentation leads to the corresponding raw file in the repo but you can’t edit anything at all. Flyby changes? Forget about it.

In so far I do not see the foundation having much interest in improving the documentation infrastructure.

Well guess what bf does use mediawiki, but not for user documentation.
https://wiki.blender.org/wiki/Main_Page

@LazyDodo

My point is Blender needs to have official user tutorials and documentations with certain quality control, be it user generated or from the studio guys. I don’t get where this notion of volunteer maintained documentation comes from. Every other DCC has official documentations either in Video form or Text, which are maintained by the development team.

A Documentation with detailed explanation of each of the components. (Micro view)
Task driven tutorials that utilizing said components to complete a goal (Macro view)

Unreal
Tutorials: https://www.unrealengine.com/en-US/onlinelearning-courses
Documentation: https://docs.unrealengine.com/4.27/en-US/

Unity
Tutorials: https://learn.unity.com/
Documentation: https://docs.unity3d.com/Manual/index.html

Affinity suite host their own video tutorials: https://affinity.serif.com/en-us/learn/

Substance Painter
User tutorials: https://substance3d.adobe.com/tutorials/courses/Getting-Started-with-Substance-3D-Painter-2021/youtube-_j27AS0VQOw
Documentation: https://substance3d.adobe.com/documentation/spdoc/substance-3d-painter-20316164.html

Blender
Tutorials https://www.blender.org/support/tutorials/ A barren wasteland of a tutorial collection
Documentation https://docs.blender.org/manual/en/latest/index.html

Just copy pasting tooltips. This is obivous and the documentation does not offer any more than what you can see in the gui itself. https://docs.blender.org/manual/en/latest/physics/particles/texture_influence.html

Blender sculpt brushes. With ToDo that are never done. https://docs.blender.org/manual/en/latest/sculpt_paint/brush/brush.html

Compare that to Zbrush http://docs.pixologic.com/user-guide/3d-modeling/sculpting/sculpting-brushes/

Hot linking external sites, with 2.79, but it demonstrate the constrain’s functionality well. https://docs.blender.org/manual/en/latest/animation/constraints/tracking/clamp_to.html

https://docs.blender.org/manual/en/latest/render/cycles/baking.html
Despite the wall of texture explaining every options,
In here you will not find active texture node means, or that to bake a texture to an image you need to add a texture node to the material and make a new texture and selected it and not connect it to anything and then hit bake and that the texture goes to the newly made texture. Nor is there any steps on how to project a high poly texture onto low poly model which is a common workflow for game asset creation. Walls of text, but nothing useful to the end user who doesn’t already know baking in blender.

You can have volunteer updating the documentation in piece meal faction, but the foundation is weak. Most of the documentation lacks usage example and illustrations. There is no concrete example on how to integrate blender into your workflow.

There is no leadership, no direction. The developers have grown complacent with all the user generated content. And us all are expected to pick up the pieces.

Maybe they can learn a thing or two from godot. https://www.youtube.com/watch?v=eBQSkGdG8zA

6 Likes
20

No, someone else suggested that. I’m saying since nobody can be bothered to setup a dev environment and learn SVN just to add 1 useful tip to 1 page on the documentation, perhaps 1 person with a web server can setup a clone of the documentation but also add a comment system on it so people with a complaint or addition for the docs can just leave it in a comment. Later, much later, one or two people with SVN & Docs system knowledge can update some parts of the docs with the useful information in the comments from the community… or that part can never happen and the person who setup the website with the docs and comments can put some adverts on there and make money if the idea of “blender docs but with super useful comments area” becomes moderately popular in the community.