利用者:Pildanovak/User Help System

Help system ideas

I am writing this document, because I got some ideas how a future help system could work. We discussed it a little in irc. My opinion is such help system would be much more maintainable and useful. It could possibly replace the wiki documentation completely, or be it's up-to-date mirror accesible directly from blender. I'm going to attempt to implement at least part of the proposed functionality, although help of any experienced coders would be welcomed anytime, since I consider myself still a beginner in c. Feel free to add anything to this document. A plan is to consult this with anybody aware of the future blender 2.5 structure and realise if the architecture could be already prepared for such help system.

Current system

tooltips:

If a user hovers over a UI block, which is happy enough to have a tooltip, a 1 liner appears. This often doesn't really show what the tool does, since the user needs an explanation rather than a complete name of the tool.
Editable directly in the .c files - only editable by developers with acces to svn.
Not available in the menus.

Wiki:

Partial documentation in more lenguages. Quite advanced english version, but obsolete in many areas(after 2.5 almost completely?).
Editable by anybody really wanting to help, with an wiki account
- now wiki gives anonim edit rights --mindrones 11:57, 14 June 2009 (UTC)).
Supports formatting, images.
User needs to be online.
Help is not linked from blender, user has to find the help.
- as a note, please see my suggestions about this in my proposal --mindrones 11:57, 14 June 2009 (UTC)

Initial unsorted ideas

Codewise as light as possible.
Everything gets cared for automatically. The user has to do as least as possible to have new piece of docs done.
Everything user-editable inside of blender.(text editor)
Simple formatting options(html parsing?) - headline, bold/italic.
Auto-generation of empty help templates.
Auto-size of tooltip window.
2 help modes - basic(single line tooltips),advanced(big tooltips with images and links)
2 ideas for display- 1 is floating tooltip, 1 is new space type - help(browser like in xsi??rather a simple text+image drawing, with 3 buttons - www, video, edit-this-help)
Auto-filling of translation versions from english version.
Support for links to www.
Support for images and outer video playback.
Translation subtitles for videos (no idea for solution now)?
Can be installed either locally, or accesed on-line.
screenshots/images for help could be done directly inside of blender during editing. Grease pencil could be used for quick pointing to area of interest.

Code ideas

Each UI block has assigned a property which it controls, or a tool which it runs. Idea is not to store any help information inside of the block code itself.
Help is completely outside, and the tooltips are adressed purely by the property/tool name.
If a mouse stops over the UI block(as now), the help file loads, the current tool/property is searched for and gets parsed. If there's an image(s), it gets loaded.Then the help is drawn in the help space(if no help space, a popup tooltip).The structures are released immediately after the tooltip disappears, or, in case of help window, another tooltip gets loaded.

Workflow/helpflow inside blender

In the help menu, there are switches for none,simple and advanced help system. In the menu, there's a switch for turning the help editing on. In the paths section, there is a help path, since this help is considered to become possibly big and not installed always in the blender directory.

a user hovers over a UI block/menu item: - if help switched off, nothing happens. - in simple mode, show a 1-line tooltip. - in advanced(tutorial) mode, show a bigger tooltip over mouse or display this tooltip in the help space. -the bigger tooltip Has several lines to several paragraphs of text, 1 small image(???), besides that there are 3 buttons:

Wiki - leads to the wiki page of documentation.(this would become obsolete if htm would be used for tooltips and each tooltip would be a mirror of it's own on the wiki)
Video - leads to a part of 1 of the tutorial videos
Edit(only available if help editing is on) - opens the helpfile inside of text editor and jumps to the position with the current tooltip. User can edit the file and save it as any other text file from blender.

Video playback

the tooltip has a video link. It starts playback of the video in the system-preconfigured browser(?).
Since there aren't as many videos as tooltips, there could be only a limited set of videos covering as many features as possible.
The link also stores video position, so that clicking on the link starts the playback+rewinds to the actual point of the video.

File formats and directories

format of text files:(in order of my current priority) xml,simplified html, .blend files, custom format. The question is if they should be compressed with the file compression already available in blender.
for
on-line storing. svn?
uploads possible directly from blender? Or at least generating patches.
patch system- patches need approval if not done by un-authorized users, trusted users could get acces.
the format of videos should be as wide as possible, lightweight, but the codec should be as good as possible for keeping the ui visible.

possible directory structure would be simple:

 help  
    tooltips
        images
    videos

Web-hosting

I don't have really good ideas for this. Blender foundation servers often can't serve all blender downloaders, and possible help system like this would probably be bigger then blender installation itself. Therefore some other solution would have to be found. Could be:

sourceforge?
youtube for on-line videos?
any other idea are welcome.

I would expect that the documentation in this form would stay very alive, so a re-downloading the whole package would be probably a bad solution. Ideas for patchy solution is:

using svn for merging the new help content
releasing a complete doc version for each release, then release a patch monthly.

pros and cons

pros:

would probably get more updates, be more alive. User which notices a part of missing documentation can fill the hole instantly and upload it.
less work for coders.
more contemporary, maybe even innovative.
ease of use, faster learning curve for blender.
more blender users !
on-line docs could be synced.

cons:

blender foundation and some devoted blender supporters/devs currently get financial support through selling tutorial dvds. A good help system would probably lower the interest for beginner tutorials and tutorials generally describing tools, although advanced help like workflow tips would be probably seeked more, since there will be more and more advanced users.
possibly download heavy, needs some good solution, maybe sponsorship.

Review

Most of this is great ideas, but it really is too big to get something started. I bet we can make things future proof with a good abstracted documentation/tips design much easier.

--Ton 17:51, 22 November 2008 (UTC)

What's the problem with just installing MediaWiki or using something like Wikibooks? http://en.wikibooks.org/wiki/Main_Page Also - imho the use of tooltips is a bad design choice in general. Icons should contain text and be easily understood. Hovering over all of them (think microsoft office) gets to be a pain really quick.

--Andriyko