Or you could migrate the doc to git and put it on github and make use of the online editing functionality and save yourself some trouble and hosting expenses.
1 Like
I think the number of people willing to argue the accuracy of some info in a comments area is 1,0000x larger than the number of people interested in making an actual edit to the page, no matter how much easier github might make it. I’d also prefer if a small team were to manually update the docs based on the comments instead of everyone being allowed to make any edit they want any time.
I think if someone wants to contribute to the manual, they have to spend time, and learn SVN, a fork does nothing but confuse more, it’s not useful, and to make the changes you also need to know the reStructuredText markup to edit the pages, the only way to do it efficiently.
I honestly don’t understand this logic. AT ALL. One would think it would be in the best interest of all parties that the barrie to contribute should be as low as possible. The person who would want to contribute is already doing a lot of work trying to offer quality contribution. The tools to add such contribution should be familiar or very easy to learn.
When there are so many barriers to overcame no wonder occasional contributor would give up before they had a chance to add value to everyone.
It’s so backwards.
2 Likes
I think it’s not much complicated, you have only to follow the steps in the documentation if you want. I’ve downloaded the whole manual by my self few years ago and is a structured work flow that make consistent the documentation, for my opinion is great choice this type.
In reality, once downloaded the documentation is so simple to integrate that a very banal text editor such as notepad is sufficient.
For example, digital books are available in various formats such as simple texts PDF Word and EPUB documents, the best to read is in my opinion the EPUB, which has its own clear and well-defined structure, but to make EPUBs you need to know its structure composed of a CSS and various components structured in a compressed file, and if you want to create for example a WEB site you should know HTML, even if there are various ways today to do it, the best results are obtained by knowing HTML.
The Blender manual made in this way offers several advantages as well as being clear and understandable from that type of document you can automatically generate an EPUB and a PDF file and it is a considerable advantage that allows you to do it without further modifications and reformatting.
This like other things need a little effort to do, and frankly it’s not like software development, you just have to learn a common and versatile tool.
Often we have to make small efforts, but I think the biggest is the time to devote to doing the documentation.
Also at the bottom of each page there is a link that allows you to directly edit the documents without making much effort, you only need to know the reStructuredTex markup language, which is very trivial and you can also create it with a simple text editor.
for example this page https://docs.blender.org/manual/en/latest/modeling/meshes/introduction.html is like this.
************
Introduction
************
Mesh Modeling typically begins with
a :doc:`Mesh Primitive </modeling/meshes/primitives>` shape (e.g. circle, cube, cylinder...).
From there you might begin editing to create a larger, more complex shape.
Modeling Modes
==============
The 3D Viewport has three principal modes that allow for the creation,
editing and manipulation of the mesh models.
Each of the three modes has a variety of tools. Some tools may be found in one or more of the modes.
Modes that used for modeling:
Object Mode
Supports basic operations such as object creation,
joining objects, managing shape keys, UV/color layers.
Edit Mode
Used for the majority of mesh editing operations.
Sculpt Mode
Instead of dealing with individual mesh elements,
supports sculpting with brushes *(not covered in this chapter)*.
https://store.blender.org/product/cycles-encyclopedia/
When I see this the first thought was: “WHY isn’t this in the documentation…?”
3 Likes
At the pace of documentation development, whatever build you have will be out of date pretty quickly. And what is there in the doc isn’t very good. I grep’d the repo and there is tons of Todos everywhere. You cannot rely on the documentation containing useful information.
You cannot directly edit from the web interface and submit patches from there. Unlike with github online editor. https://docs.github.com/en/codespaces/the-githubdev-web-based-editor
And the patch submission process isn’t good.
The download instruction defaults to 3.0 master branch while the docs.blender.org defaults to 2.93. Say you see something wrong with the doc, when you downloaded the repo and edit it, you are editing 3.0 which might be different from what you are seeing online. This is not mentioned in the contributing.txt
There is also a total lack of instructions on navigating phabricator. The revision requires tagging repository but the repo isn’t named documentation it is blender manual, this is not mentioned in the contributing.txt
But when you create the revision you do tag documentation. why is the same thing refereed in two different ways?
I was on phabricator and I wanted to submit a patch from within the interface. This button took me 5 minutes to find. 
I am upgrading the difficulty of submitting patches to a full pablo dobarro. I do not expect a “normal” artist to be able or willing to spend the time to navigate the process required to submit a patch. The process is goddamn awful.
My point still stands, making a video on youtube is easier than contributing to the doc.
The team is happily hammering away at the geometry node while the rest of the documentation sits gathering dust. It certainly gives the impression that documentation is only for a small circle of people. I have submit two patches on monday and wednesday today, and I have yet to see anyone reviewing them.
On the developer wiki there lists three ways of contacting devs.
- Assign or CC them when submitting the patch on developer.blender.org.
- Subscribe to the bf-committers mailing list and send a mail that you added a patch.
- Go on #blender-coders on blender.chat and talk to developers.
And one of them just outright don’t work for the doc team. Why are they so special? I am convinced that there is no reviewer.
When I see the level of activities on the mailing list, the devtalk board
If the process is not improved the documentation will rot.
1 Like
This happened before, now every developer before release must also create documentation for new features, likely that these are not exhaustive but has been so for some time.
Done! Thanks for the recommendation (sorry it took so long; I’ve been having slow internet the last few days).
Now… as to the topic, I suppose a history lesson is in order.
In fact, Blender’s documentation had actually been on a wiki in the past. The trouble was that it was difficult to maintain and community contribution was low (“You mean I need to register with another page? That’s too much effort!”… I’m not kidding, you can find people saying that here if you look back in the archives far enough). So to ease the maintenance burden and cater more to the people who were putting in effort on the documentation, it was migrated to the current system that’s in place (ReStructured Text and Subversion).
That said, when that migration happened, there was certainly a discussion about the increased barrier to entry for “one-off” contributions. Things like fixing typos or modifying a single page. The standing recommendation there, much like the rest of Blender, is to file a bug report. There’s even a Documentation section on developer.blender.org with a handy link there on the left sidebar for reporting a bug in the documentation.
Your bug report on the documentation could be as small as “there’s a typo on this page” or as big as, “please put this whole new paragraph with images in over on this page.” You don’t even have to format the text using RST or create a proper patch to the documentation (though that’s always appreciated).
So, the barrier to entry for contributing to documentation is actually no higher than that of reporting a bug to Blender… something we all can and should do as well.
5 Likes
Very interesting. I did not know this. Perhaps it should be communicated better so that
more people are aware of this.
Perhaps it would be enough to automatically insert a button and short text i the beginning of every page that tells you that you! can report an error or suggest a change. Calling it reporting a bug will confuse people.
There should be a link near the bottom of every manual page
Not sure what the edit one is for, since Just got me to a history page, but the Report bug one opens up the bug submission form, with a bunch of information like the page in question already prefilled.
Report Bug could perhaps be rephrased to be more inclusive of other improvements ie Report Bug or Improvement
6 Likes
Yes, never in my life would I have guessed that I can suggest changes or even report spelling mistakes under “Report Bug”.
Actually I never noticed this link either. Perhaps it would be better to put it somewhere more visible.
Perhaps right at the top in an “in your face” color. At least until awareness for this has been raised.
2 Likes
Seems to me like you’ve discovered the first bug with the documentation that you’d like to report. 
4 Likes
this is so meta
2 Likes
Just reported this meta bug. 
3 Likes
blender’s doc is quite pathetic comparing to vray’s
- An example render.
- renders with different parameters are shown.
https://docs.blender.org/manual/en/latest/render/shader_nodes/shader/hair.html
- Real world references
- Example file provided.
- example node graph setup
Now that I dug through the documentation a bit more, there are few pages here and there with some renders from the book. Pretty clear that the author of the book is not against having their work incorporated into the doc.
Sometimes you get what you pay for.
If blender got paid for every user the same amount that chaos group did, there would be a lot more resources available for documentation.
But feel free to donate your time and effort to resolve these insufficiencies you have found.
7 Likes
I did send a patch updating the image.
A relative some patch updating three images.
The review took a month.
I will reconsider when their migrated to git. Svn annoys me.
You who didn’t try to contribute did not see the deficiency of the infrastructure and review process, which I have outlined above. Those I cannot help.