Looks to me rather mixed (thought maybe a few more pages put the image above).

Not sure if work is being done on this already (T42947)? A lot of screenshots need updating too.

Thanks @Campbell Barton (campbellbarton) I will try to work on setting up the environment for working on these hopefully by the end of the month

Hi. I found this task thread after I posted my comment to https://developer.blender.org/rBM651

It seems to me that there is some ongoing inconsistency about where the images should be.

For example, the markup style guide says the following:
Markup Style Guide, Images, Usage Guides

Quote:
"Avoid specifying the resolution of the image or its alignment, so that the theme can handle the images consistently and provide the best layout across different screen sizes.

When documenting a panel or section of the UI, it is better to use a single image that shows all of the relevant area (rather than multiple images for each icon or button) placed at the top of the section you are writing, and then explain the features in the order that they appear in the image."

^ Surely it is better to place an image of the UI section being explained before the actual explanation. It seems much more logical, especially if the main purpose of a page is to describe a particular section of the UI. Exceptions to this rule may be necessary for images that are provided for illustrative purposes, or as examples, but I do not think that the main image of a UI section should ever be placed at the bottom of the article.

Cheers,
AgentSam

@Samuel Sebastian Tekrenius (AgentSam) you make a good point and a agree with you however a lot of theses pages are only a paragraph or two. So for these pages its fine at the bottom and with longer pages I think images should go under the introduction.

This puts us in a position where, as document writers/contributors, we don't know for sure what type of style to use and where, as far as these image elements are concerned. (Although I'm sure there are other parts of the style guide that remain vague.)

Let's talk about that.

I would propose that before implementing any image position related changes on a larger scale, we should first fix the style guide; ie. to come up with a guideline that everyone can follow, and easily locate. As reading the style guide is the first step any new documentation contributor will/should do.

Cheers,
AgentSam

I personally like having the image above the text, assuming the text consists of a list/description of the options visible in the image.

Having the image on top visually shows the user what settings are talked about at a single glance, without the need to scroll down.
Having the image at the bottom could potentially result in the user not noticing the image until the text has already been read (and IMO such text usually makes more sense when read with an image in mind).

I know that the writing style says to stay way from defining an images position but (at least for the node cases) I feel that having the general districting of the node with its picture on the left with the details of the settings below. This way the image is in the view while reading the disruption without having a large plank spot with just an image.

I think that'll require some custom css stuffs on our end. I wouldn't mind fiddling around with it, but imo it's not a huge priority at this stage.

Here is an example of aligned to the right:

I think I will start committing these changes unless people don't like the set up

Ah, nice!

Looks good to me, but I think for now we should keep this just on the node editor (to avoid giving the impression that all images should be floated like this).
Perhaps having a list of all situations where this is ideal would be good (i.e. nodes, modifiers? constraints?).

Agreed... committing fix for matte nodes

I am simply going to add a style note then close this. Then this cane be improved on in the future and no task is needed.