[Bf-committers] Blender doc intergration proposal

[Mats Holmberg]

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)
>
> 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 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.
>
>
> On Implimentation, each button would have a  URL relative URL to  
> "http://mediawiki.blender.org" in its tooltip.
> The "Render" tooltip might be "Start The 
> Rendering|/index.php/blendocs/scene_buttons/render#render_button"
>
> Its no big deal to modify the tooltip function not to render anything 
> after '|' (can be any char realy) and make a modifier key launch a web 
> browser when accessing the button/slider/text input etc.
> This also wont break with buttons that dont have URL's, they just wont 
> open a help page-
>
> it will be easy to add documentation to python scripts too because 
> they just need the URL in there tooltip too.
>
> Elubie suggested but we could have a downloadable version so people 
> could use locally instead of http://mediawiki.blender.org
> The userprefs could have an entry for docroot so the right page opens up.
>
> If for whatever reason it dosnt work as well as expected, and we dont 
> want to include in a release, we can just disable the browser loading 
> functionality for that release. (while still writing more docs)
>
> What do ya think? - worth writing a patch?
>
> - Cam


Sounds like a working idea. As I see it the problem with tooltips is, as 
you mentioned, that it's quite hard to write concise information about 
3d related terminology, and programmers who make the buttons have other 
things to worry about. Tooltips are usually made useless, take a look at 
any OS. In blender there are same kind of symptoms - in the 'render' 
button example, having a tooltip like 'start the rendering' is the same 
as having no tooltip at all. What the user really wants to know is what 
'render' means and whether he/she should press the renderbutton (ie what 
will happen). For that info to come across there should be a tooltip 
explaining the result of what happens when the program renders - not 
that it starts rendering (which is obvious for each and every one). But 
as an addition to this the possibility to learn about rendering through 
a wiki page sounds nice to me. That way someone who really wants to 
learn blender could explore the program on his own, not just following 
tutorials.

I'm more than happy to help out with tooltips themselves, if needed 
(contentwise). I just don't know how to go about making changes =)

Mats