[Bf-docboard] General suggestions: layout (margins) & GUI screenshots

[Campbell Barton]

Hi Cal, reply inline.

On Wed, Jan 21, 2015 at 7:46 PM, Cal McGaugh <cal at cal3d.com> wrote:
> Hello everyone,
>
>
> I'm glad to see the new manual format. Much easier to read, better
> navigation, and
>
> it will be great to be able to print the manual (eventually).
>
>
> Here are some suggestions:
>
>
> make the margin on the right equal in width to that on the left.
> But if we can download the manual, and the CSS, each user
> can do that for themselves (?)
>
> Would like to see more full screenshots of the GUI at least in the Intro
> page of
> each chapter, e.g. Physics (see screenshot)
>
> Too often I see a page describing a set of functions, with only a small
> image of the
> relevant part of the GUI, without first showing where to find it in the
> whole GUI.

Establishing images can be good, say - for each chapter.
But adding a lot of images gets really time consuming to keep up to
date, just see how many images we still have from Blender 2.4x.
We cant (at the moment) realistically have images for every node, or
menu... it just gives us a lot of work, so prefer to use images only
when its really needed.

> In the case of Physics, for each type of sim,  show the set of controls that
> are specific
> for each, e.g. Fluids,  and an explanation of what
>
> and explain each control or input more fully. Some explanations are too
> short to be helpful; others
> need to be edited to shorten, and/or broken into paragraphs.

Yep, we miss good introductory text in many areas.
Its come up before - "Why would you even use feature ____ ?"

> Break up blocks of text into shorter paragraphs for easier reading
> comprehension
> e.g. on this page under Default, split it into 2 paragraphs

Good to avoid walls of text, otherwise dont have strong opinion,....
would evaluate case-by-case.

> Would like to see more embedded videos to show the effects

We can embed youtube or vimeo, would try to keep this for examples
only. Step by step instructions go out of date too fast & need to be
re-recorded.

> Navigation.....all things Fluid need to be grouped together......as is, they
> are scattered in the list.....e.g. Fluid Simulation......farther down the
> list, Fluid Physics......Fluid Domain, Fluid Object, Fluid
> Obstacle......farther down, Fluid Technical Details, Fluid Appendix
>
> How about a 2nd list that would expand under Fluids to include all the
> sub-topics?
>
> Text links in the content should be bolded vs italics, and a darker color
> for contrast

I expect this may be an changed with the theme. There are quite a few
themes available.

http://sphinx-doc.org/theming.html

Unless its really essential I rather not invest a lot of time in
changing the theme, and call the current theme *good-enough*, and
focus on manual content, Since the theme can be change any time we can
better get a usable manual ready first.

> I'd be willing to help, and did try 2 yrs ago on the Wiki, but wasn't sure
> who was responsible for each page,
>
> and didn't understand the Wiki method well. Better communication between the
> editors and those in
> charge of the project would be good.
>
> If things are more clear cut now, I'd be inclined to work on it. :)
>
>
> Great job so far. It looks like it will be easier to update and maintain.
>
>
> Thanks,
>
> Cal McGaugh
>
>
>
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
- Campbell