[Bf-docboard] Documentation status and upgrade proposal

[koil .]

I dunno.

I remember being determined to update the wiki after seing the same void pages for years.
I wasnt great at adding content when I started, and I see im not adding some of the correct content now.
So I can try and adapt, but it seems there will probably a new process in the future anyway.

..

Usually I copied 2.4 or added the same kind of content others added.
Which kinda grew in to this style.

Intro
- What it does. What its used for.

Elements
- Parts unique to the user interface or subject.

UI Reference
- Reference for panels, header buttons, with extra info.

Menu Reference
- Reference for the menus in the editor.

Editing Reference
- Relative operators with context mode and keyboard reference.

Workflow
- An example of a process or hidden process related to the subject.

Examples
- Examples with a picture, description, and maybe blend file.

Trouble Shooting
- Common problems related to the subject.

Notes
- Importent notes related to the subject.

There wasnt really a guide on what content to write. There were some examples but it wasnt well defined.

I kind of realize the reference is not something desired, and I agree.
I think it can be good for some pages like keying sets: http://wiki.blender.org/index.php/Doc:2.6/Manual/Animation/Basics/Keying_Sets
Its nice way to find an operator or property, but not all operators and properties need to be reference.

I dont think its good for editors, with the header menus.
With an editor its probably best to write an editing page with basic controls.
Its probably best to just describe what the panels are for and only add extra info for different properties and operators if desired.

I would like it if there was more info, like What To and What Not To write, with well defined examples.
But thats up to the developers.

..

Anyway from what ive read so far, I like what is proposed.

I like the process of a user saying, 'Hey thats not mentioned in the doc, add to doc' like a bug report.
This would probably be a better process to follow.
Theres some features for Drivers ive recently discovered, like adding #frame to a property will add a scripted expression driver.
And if a user wants scripted expression objects to update in the UI, they have to add the object id to a driver variable.
These would be good Bug Report/Todo examples.

Id also rather follow a process of adding proposed fixes for TODO's to a webpage, then its up to a developer/reviewer to add, partially add, reject, and give feedback.

I think the current old Writers Guide can be a hard read for new users.
If you do want user contribution, It would be nice if a new one could be written, for if/when to new manual is online.

..

I probably wont update the wiki doc much this year, unless a new directive is added.

I like the new webpage for the doc, and I hope it works, if user contributions exist or not.

Koilz.
 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140507/5c91c66b/attachment.htm