Suggestions on General Documentation Approach

Blender documentation projects, tutorials, translation, learning & teaching Blender

Moderators: jesterKing, stiv

Post Reply
rben13
Posts: 0
Joined: Mon Feb 25, 2008 7:30 pm
Location: Boston

Suggestions on General Documentation Approach

Post by rben13 »

I've been trying to figure out how to do some particle stuff and I keep coming across out-of-date documentation and incomplete documentation. Part of the problem, of course, is the speed at which Blender changes. It takes a long time to write good documentation, provide examples, and make screen shots, and it is frustrating to do so and then find your work is out-of-date already.

There may be a way to help, a bit. Here are my suggestions. (I realize some may have been made before.):

* Have a central repository for screen shots of all the interface panels for Blender. The repository should be organized by version number and variant. So, for instance, there might be a directory structure like:

Code: Select all

./blender/docs/scrn/if_panels/248/common
./blender/docs/scrn/if_panels/248/win/common
./blender/docs/scrn/if_panels/248/win/32
./blender/docs/scrn/if_panels/248/win/64
./blender/docs/scrn/if_panels/248/linux/common
./blender/docs/scrn/if_panels/248/linux/32
./blender/docs/scrn/if_panels/248/linux/64
./blender/docs/scrn/if_panels/248/linux/Ubuntu/810
./blender/docs/scrn/if_panels/248/volumetrics
./blender/docs/scrn/if_panels/250/beta 
./blender/docs/scrn/if_panels/250/common
./blender/docs/scrn/if_panels/246/common
(This is just a first stab at this idea. Please don't get hung up on nits.)

Then, we'd want to provide pictures of each of the panels in each state needed for documentation. That way, if I'm writing a bit of new documentation, I don't have to produce my own graphics. I can probably grab one from the std graphics directories. If I do need to add one, I put it in those directories in order to make it easier for someone who is updating the documentation.

Ideally, we would find some way to create the various panel graphics programatically. Since the I/F is mostly Python, that should be doable, shouldn't it? Perhaps each I/F widget needs to have an accompanying framework that can be used to provide a graphic of that widget in any specified configuration. Then, when changes are made, the process of updating the panel graphics could be automatic.

This also might make it easier for patch authors to produce customized versions of the documentation for their respective versions. That might make it easier to get good testing, acceptance, and merging into the regular branch.

---

I also think we should have a standardized approach to doing certain kinds of documentation. For instance, in trying to figure out how to use the particle system, it would have been really helpful to me to have small examples given, in text and perhaps in a graphic, that would show how each of the various options. Billboard is noticeably absent in current docs. (I still haven't figure out what it's used for.)

---

These are not easy things to do. They will take a lot of work. If I had the time and energy to do it all myself, I would, but like everyone else, I have multiple demands on my time.

So, what do you think? Is this all fantasy, or do some of you think this is doable?

Ray

m.ardito
Posts: 2
Joined: Wed Oct 16, 2002 12:30 pm

Re: Suggestions on General Documentation Approach

Post by m.ardito »

rben13 wrote:I've been trying to figure out how to do some particle stuff and I keep coming across out-of-date documentation and incomplete documentation. Part of the problem, of course, is the speed at which Blender changes. It takes a long time to write good documentation, provide examples, and make screen shots, and it is frustrating to do so and then find your work is out-of-date already.

There may be a way to help, a bit. Here are my suggestions. (I realize some may have been made before.):
<snip>
Ray
I agree, and like the idea... sometimes i think blender devs should slow down releases (which are usually so frequent, apart from the big gap whe're having to 2.50 but that's a giant leap...) and release ONLY after there's documentation, and each release should keep its own documentation. the wiki is good but most people need to refer to the whole documentation for each official release of blender.

my 2c
Marco

rben13
Posts: 0
Joined: Mon Feb 25, 2008 7:30 pm
Location: Boston

Post by rben13 »

I suspect it is the rapid advancement of Blender features that makes Blender the wonderful tool and community that it is. While it's tempting to apply the brakes, the real trick is to find ways in which we can produce and update documentation at a pace which can match that of development.

I've been thinking more about my original idea. I believe most of what I want to do can be accomplished with a python script. The script would take a panel description object, maybe called panel_def, and would add a field to the object for each field on the panel where you want a value other than the default. The description object would also have a pointer to the code that produces the panel. (Very easy if it's python code, probably a bit complicated if it's C, but not impossible.) Then you call a new routine, perhaps named generate_panel_graphic and pass it the information. the routine would write out a .png file holding the image of the panel in the desired state.

Here's a rough example:

Code: Select all

panel_def.version = "2.48"
panel_def.name = "Material"
panel_def.location = "../../some directory"
panel_def.texface = "on"
panel_def.no_mist= "on"
generate_panel_graphic(panel_def)
If we did it that way, we could generate documentation and graphics on demand. A particular section of the manual would not have to be checked to see if it had been made out-of-date simply because a panel had new options on it that aren't relevant to that part of the manual.[/code]

stiv
Posts: 0
Joined: Tue Aug 05, 2003 7:58 am
Location: 45N 86W

Post by stiv »

Since the I/F is mostly Python, that should be doable,
Point of information: It is not. The UI is done in C.

Robel2008
Posts: 0
Joined: Sun Feb 22, 2009 8:33 pm

object for each field on the panel

Post by Robel2008 »

I want to do can be accomplished with a python script. The script would take a panel description object, maybe called panel_def, and would add a field to the object for each field on the panel where you want a value other than the default. The description object would also have a pointer to the code that produces the panel. (Very easy if it's python code,

Post Reply