Going through the manual for the various Cycles nodes, I’m finding that much of the documentation requires in-depth knowledge of light physics to understand.
The Layer Weight node outputs a weight typically used for layering shaders with the Mix Shader node.
Provides no description of what the node actually does. (I have had this resolved myself in a separate topic)
According to the Writing Style Guide one of the main goals for the manual is:
User Focused
While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users.
These pages, along with many of the cycles node pages, appear to be written by people who are well aware of the physical simulations involved, but forget that others don’t. As a programmer, I have been guilty of this myself, so I understand the issue I trying to document for someone unfamiliar with the inner working of system. I would fix these issues myself, but I am not familiar enough with the topics to provide a descriptions.
I’m not disagreeing with you here, the manual could be better in many places, and as you noticed great programmers do tend to make not so great tech writers, what is great however that like the blender software, the blender manual is a complete open source project and anyone willing can get involved.
Even if you can’t write a line of code to save your life, but you know how to explain things, hop on board! More information on how to start contributing to the manual can be found here.
If you’re still unsure and want a concrete example on how to submit changes, here is a change I recently submitted to document the operations of the vector math node.
I’m on the same slippery slope though,the output for instance of the normalize operation returns the length of the original input vector in the value socket, I documented it as |input_1| while it should make sense to anyone who ever worked with vectors, it may be confusing for the more novice users, it’s a tricky balance to strike and as you noticed they don’t always get it right.
Something a read a few days ago stands out in my mind, which really made me appreciate the documentation team. It’s easy to forget that a lot of volunteer work goes into Blender’s ecosystem.
Indeed. I guess I’m just trying to highlight things in the hope that someone with a better handle on it might be able to make some clarifications. More of an appeal for updates.
I’ve made a few updates before where I’m able to, but these particular items are currently beyond my ken. If I get time, I can make some updates based on code analysis, but I’ll need to do some more research on the shaders to understand some of the intricacies.
The terms ‘Dielectric’ and ‘Anisotropic’ have the same meaning as in the scientific community. I don’t think the manual should try to explain what they mean… There’s wikipedia for that.
For the SSS parameters or the ‘Layer Weight’, thought, we could have a better description, as those values are much more specific to cycles’ innerwork.
As others have said, these are industry standard naming conventions, they aren’t specific to cycles. Most other renderers documentation also doesn’t go into detail about things like that. A simple google will suffice.
It’s my understanding they actually quite distinct. Dielectric basically is a non-mettalic surface, Anisotropic refers to something like the brushed steel effect on a pan where light is forced into more elongated specular reflection.
He isn’t saying that ‘Dielectric’ and ‘Anisotropic’ are synonyms. He is saying that they each have the same meaning in Cycles as they have in the physical world. As such if you Google dielectric you will get a definition.
The main goals for this manual are as follows:
… User Focused
While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users. Complete
So there is a canonical source of truth for each of Blender’s key areas. This does not mean we have to document every small detail, but users should not have to rely on searching elsewhere to find the purpose of key features.
So saying, “There’s wikipedia for that”, is actually in opposition to the purpose of the manual. Also, I looked at Wikipedia. The article on Dielectric talks about the electical properties, not the optical properties. And for Anisotropy, the description is quite vague.
The whole statement of “The terms ‘Dielectric’ and ‘Anisotropic’ have the same meaning as in the scientific community. I don’t think the manual should try to explain what they mean.” is exactly the issue I’m describing. Blender is a graphics program, so the majority of target users will be coming from an artistic background, not a scientific background; you shouldn’t have to learn new scientific terms just to use it. To say things that equate to “If you don’t know what that means, I’m not going to tell you” is bordering on elitism, and the Blender community usually strives to be accessible to newcomers.
I get where you’re coming from here, and it would certainly be helpful to have such a scope of info in the documentation, but I don’t know that it’s the function of the Blender documentation to define standard terminology. Blender documentation is there to explain Blender features. ‘Dielectric’ and ‘anistropic’ are general terms that belong in sources of information with a broader scope of shader theory in general.
Where would you draw the line between documenting Blender, and documenting the entire practice of CGI in general?
Do we expect all our users to be well versed in shader theory? Isn’t the point of a node-based system to abstract away from that? It’s like writing a game and telling the player to decrease the resistance on the Y1 potentiometer, instead of saying push forward on the joystick. Try searching “dielectric” and see how long it takes to find relevant information. “Non-Metallic” would probably be a better term, as it makes sense to more people.
For me as a user, I expect to be able to read the manual and see things that explain the visual effect of what it does without having to spend hours researching and learning new concepts just to find out that it isn’t what I’m looking for. Honestly, I think these thing will more likely push away potential new users; They may stick with Internal Render, or they may just give up.
I think glossary entries and links to them would probably solve the problem. I’m submitting some doc updates at the moment for a couple of things. Perhaps, simple descriptions in the glossary that describe enough to allow use of the program, without having to delve into the physics.
BlockquoteThe terms ‘Dielectric’ and ‘Anisotropic’ have the same meaning as in the scientific community. I don’t think the manual should try to explain what they mean… There’s wikipedia for that.
So fine, it’s a quantity related to the permitivity of free space that specifies the ability of a capacitor of a given plate area and gap to store charge measured in Coulombs, or whatever my ancient GCSE physics O level taught me.
Honestly, this is pure snobwankery. The “well if you don’t know what it means I’m not going to tell you” stuff. It’s a manual. It’s supposed to tell you how to use the thing it’s a manual for. Now look, I do appreciate that documentation is a dying art and it’s a long time since you got a block of books twice the size of the computer you’d bought, in a ring binder, with a notes section, written by somebody who actually cared if you could use the damned thing, but this style-
“Combobulation: this allows you to set the degree of combobulation” style is not worth writing. Just leaving it blank is better, frankly.
There’s a bit of a catch-22 when it comes to users improving the documentation. The areas most in need of documenting are the areas no-one really seems to understand.
You SHOULD be researching and learning new concepts, before you even begin using them. One of the biggest mistakes a lot of beginners make is trying to jump into the deep end of a specific program, rather than building a foundation and gaining a broader perspective on general concepts. It stunts growth. Over the 15 years I’ve been doing this, I’ve met many artists that can’t troubleshoot problems because they didn’t learn the fundamentals. They just learned to press a series of buttons.
If you’re not understanding the concepts involved, you should be taking a step back and working on your foundation some more before you start working on the walls. Please don’t take that personal. It’s just perspective.
Very true. I’ve gained some insight through the code, but there’s a limit. As is the usual problem with documentation, what is the right level: Assume the read knows nothing, or assume the reader knows everything. I know I myself finding the right shade of grey difficult.
This is why writing documentation is, like many overlooked crafts, a craft. A profession. Whatever.
Sort of relevant, I happen to work in a call centre. Over my two years doing this, I’ve spent much of it working out ways to explain things to people with different levels of knowledge. One of the 101s is to avoid jargon. One of the useful skills you develop is finding a way to describe something that makes sense to the person.
So here’s the thing really; this is not an internalised decision of the author or helpdesker or what have you to decide where you are pitching. Your audience decides that. They are the ones with the need for understanding, and if you have pitched at (imaginary) Level 4, and they are Level 1, you are wasting your time. Don’t bother writing, or talking. You’ve failed.
Many of my colleagues find the job frustrating, dealing with “stupid people”. Personally I love it. I feel achievement when the caller has achieved their goal. It’s fulfilling. As such I’d be happy to bring some explanatory skills to the Blender documentation myself…
…except this stuff isn’t documented so I haven’t got a farking clue what half of it does either. Not in a specific sense. I type numbers into parameters until they work, but what the actual relationships are I have no idea. What is structural stiffness in Cloth an actual parameter of? Dunno. 5.3 seems to work this time. Find for blundering on, no use for documenting it.
The people doing the documentation need to be able to interact with the engineers to get an understanding that they can convey. And they need to be able to pitch it so others can understand.
Otherwise it’s “adjust the combobulation using the combobulation setting” and that’s no use at all.
Maybe it helps to understand this if you’ve done a job where you can’t just sit back and tell people to go and educate themselves. And I’m sorry if I’ve been less than civil, but it cheeses me off something rotten, so it does.
I must admit, as a programmer, I’ve become annoyed with the drag-and-drop generation that don’t understand the basics (as I learned through assembly).
Perhaps, rather than saying “you should learn this before you started” perhaps we need to look at saying: “Here’s some links that will help you understand before diving in”. A primer, if you will.
@jaxtraw & @Jaguar, I’m not saying that the Manual doesn’t lack of some relevant information, nor that some topics are poorly writen… But we need to trace a line between writing a Manual and a CrashCourse_to_3D! When we use the word ‘Plane’ or ‘Cube’ in the manual, it’s expected that the user is familiar with these terms; it’s not the function of the Manual to explain every terms of the common terminology of 3D…
First, Blender is far more than a graphics program!
Second, this recurrent image that artists are dumb and can’t learn anything else is just old and sad. And this is particularly important if the artist wants to use some supra-technical tool like a 3D software.
People educated in computer graphics, who understand the basics of 3D and/or know other 3D software."
So there you have it. It is intended for people who are already familiar with nomenclature.
Anyways I can see where you are coming from and agree with certain points.
That said I think it would be a good idea to stick heads together and make sure, that at least the manual for 2.8 will be somewhat more readable.
While every one of us can work on the manual individually I’d rather propose to group up in a team to coordinate the works on 2.8 manual. That way there might be a chance that we can get a “dev-contact” at BF for clarifying those uncertain parts.
I think they’d be happy to answer questions coming from one source rather than fragmented random inquiries. I’ve seen a ‘documentation team’ mentioned but can’t find any hints on who they are. And how contact, maybe join them.
Any one having more insight?
Who else might be willing to join such a project?
