Helki

This page describes a proposal for a new system to link error messages in the GUI with our wiki. This has not been implemented or even decided to be implemented, please feel free to add your thoughts.

Motivation

 * Get feedback on the frequency of errors for real users
 * Provide troubleshooting information to users in a very direct and easily accessible format.
 * Crowdsource the generation of that troubleshooting information.

User's Perspective
Whenever an error message appears, a Helki link is included. Errors with links could be due to internal problems, or because the user broke a rule. This link does not replace the error message, and should be obvious but reasonably unobtrusive. The link points at an existing page in the product's wiki, which is specific to the particular error message. Permissions of the wiki page allow for any registered user to edit the page. If no user has edited the page so far, a template is provided with links to general troubleshooting information, the product's bug tracker, and user manuals. The template includes some guidance on the type of content that would be useful to add to the page. In some instances, the wiki page might be replaced with a redirect to another part of the wiki, or a bug tracker ticket.



Example Helki Wiki Page Template
This page is an automatically generated part of the FreeCAD wiki, please feel free to change it. Our user's manual and Forum are excellent resources, or if you've found a bug our issue tracker is at http://freecadweb.org/tracker. Contact one of the administrators for more information on getting an account and editing our wiki.

Once you've resolved your issue, please come back here (don't forget to bookmark this page) and update with any information that might be helpful for the next person. Thanks! --The FreeCAD Community

Example edited Helki wiki page
This dialog indicates that a 2-D drawing like the ones created by the Sketcher workbench must be selected in the before a revolution can be generated based on that drawing. See this tutorial for an example.

Developer's Perspective
Each time a new error message is created, insert a HELKI_URL or HELKI_LINK into the source code for displaying error, as appropriate. The Helki script will replace these with dummy URLs or HTML links, or with valid ones including a unique ID for each message when the code is ready for publishing. When the unique ID is generated, a template page with the corresponding ID will be created on the wiki.

developer@somecomputer src/$ helki --dummy Creating dummy links, don't forget to re-run with --publish before pushing to the public! Using configuration file helki.cfg Processed 3 new URLs and 2 new links in Mod/Example/Gui/someFile.cpp Processed 1 new links in Mod/Example/Gui/someOtherFile.py Done! ... Bit more coding ... developer@somecomputer src/$ helki --publish Using configuration file helki.cfg Processed 3 dummy URLs and 2 dummy links in Mod/Example/Gui/someFile.cpp Processed 1 new URLs 1 dummy links in Mod/Example/Gui/someOtherFile.py Links have IDs s76dhw892k r93jeld9fn asl238ekd1 qud84htkf9 fl489tjd8c ed93nmflo2 leior03mjf Pushing new IDs to the wiki........Success! If the creation of wiki pages fails, the program will support re-trying, and there will also be a manual Helki page creation option.

Wiki Maintainer's Perspective
Helki pages will be generated based on settings in a configuration file that's included in the project's source code. Wiki access will need to be easy for users to setup. A script for changing all Helki template pages will need to be developed.

Points to Consider

 * If the ID is based on the generation time, then we don't need to worry about IDs clashing.
 * Developers might be interested to know how many hits particular Heki pages have gotten, so a report generation tool might need to be developed.
 * Helki links could incorporate the user's FreeCAD language settings, to point to a wiki page in the appropriate language. The ID should be tied just to the error message, so that a multilingual user could find the Helki page for an error, in other languages.