[Bf-committers] Blender doc intergration proposal

[Campbell Barton]

Stephen Swaney wrote:
> On Mon, Apr 10, 2006 at 08:04:24AM +1000, Campbell Barton wrote:
>   
>> Hey all,
>>
>> For a while is bothered me that tooltips dont realy explain enough 
>> (because there only single line to work with)
>>     
>
>
> The purpose of tooltips is NOT to explain something but to simply act
> as a reminder for what a button or cryptic icon does. 
Ill have to defend myself here, This WAS when I first started using 
Blender :)

The reason I initially wanted this kind of info in a tooltip was that 
the info often isnt available anywhere else.

In some cases Blender's tooltips Do explain what the buttons to- Taker 
render "XPARTS" - it tells the user how xparts effects panorama.
Or look at most of the Fluid sim buttons, some have to explain what they 
do..

...if "The purpose of tooltips is NOT to explain something"
   - then is this wrong? (take a look at  the fluidsim tips, some a 
really long) and helpfull.

The problem is that there is no quickly available info that can be 
accessed from a button. - so tooltips are being (ab)used to have some of 
that info there.
Good docs are a part way solution, but the user still has to thumb 
through those docs.

F1 issue wont work, so RMB->Help Menu OR Help button then click on the 
button.. either way its not a blocker.

- I was thinking that each button have a weblink (without the 
"http://www.blender.org/docs" or whatever root path)
And that link has NO info, Rather a blank wiki that anyone can populate.

We can see how many buttons get documented just with the testing builds..

IFDEFS can be used so that if the docs arnt ready for release, the 
feature is not compiled in. (or we could release and have users fill in 
the blanks)

As for existing docs, are there any existing docs for blender that are 
current?- the manual I saw last was for 2.37 - some of the best docs 
seem to be in the release logs.. which isnt a good place for users to 
find info.

We have to accept that no 1 person is going to magically do all blender 
docs, so why not hand it to the community.

>   
>> Anyhow, possibly a better solution is to have a documentation system 
>> built into Blender,
>> It could work by the user holding F1 and clicking a button. - This would 
>> open up a webpage with documentation on that function.
>>     
>
>
> Having a help system built into blender is an interesting idea.  The
> two big issues are finding someone to maintain it and the actual
> implemtation.  The 'who' is important because a help system that
> returns "no help available" too often quickly turns into an annoyance
> rather than a feature.
>
> The F1 button is already used for the File Open dialog.  An alternate
> implementation might be a click on a Help button followed by a click
> on the UI widget of interest.
>
>  
>   
>> Having docs that are quickly accessed are important because it gives 
>> users fast access to docs that they might otherwise not know where to 
>> look for. or waist time searching about for documentation on a button 
>> that may not even be written yet.
>>
>> This could be done in a way that makes docs readable - each button group 
>> could be 1 page, with an introduction. each windows header would be 1 
>> page also. with anchors for each button.
>> And we could start by taking some existing documentation and modifying 
>> it, and also document things that are not likely to change on the 
>> Tool/UI refactor.
>>     
>
>
> Having a another set of docs for the help system is both a major
> project and a duplication of existing work.  This suggests that
> linking into the existing wiki docs is the easist solution.  Most
> browsers have a remote command that allows an application to open a
> browser page.
>
> This idea is big enough that it needs an actual design proposal rather
> than just a patch.
>
>   


-- 
Campbell J Barton

133 Hope Street
Geelong West, Victoria 3218 Australia

URL:    http://www.metavr.com
e-mail: cbarton at metavr.com
phone: AU (03) 5229 0241