[Geany-devel] Ideas on increasing quality of plugins

Matthew Brush matthewbrush at xxxxx
Fri Mar 11 23:36:50 UTC 2011


On 03/11/11 14:43, Frank Lanitz wrote:
> On Wed, 09 Mar 2011 07:27:06 -0800
> Matthew Brush<matthewbrush at gmail.com>  wrote:
>
>> On 03/09/11 03:42, Frank Lanitz wrote:
>>> Hi,
>>>
>>>
>>> Am 23.02.2011 01:10, schrieb Matthew Brush:
>>>> Another thing could be to make mandatory that documentation is
>>>> existent and current, up to some standard.  I mean for README,
>>>> manual, and also doc-comments in code (ex. each function/global
>>>> must have a comment or something).  Some other items where
>>>> documentation could be enforced; new keybindings, preferences,
>>>> menu/toolbar items, tabs.
>>> I agree in a general view. According to code comments I'm not sure.
>>> But can you give me some more details what did you think about when
>>> you referred to the keybindings, preferences etc.?
>> Sure!  The perfect example, although I haven't tried it in a little
>> bit, is the Debugger plugin.  You load the plugin and see the tab in
>> the Message Window, and it looks really cool and useful.  Obviously I
>> wanted to try it out right away, so I start to hover over the GUI
>> elements hoping for some tooltips to guide me to what to do, but
>> nope.  There was nothing in the README (at least when I tried).  So
>> then I tried to just figure it out.  Finally after about 10 minutes I
>> figure out that "Target" means the binary executable you want to
>> debug, which seems kinda obvious now, but at the time the wording
>> alone of "target" didn't seem to cut it.
>>
>> So after that now I want to run it.  I spent another 10-15 minutes
>> looking through the Toolbar, Build menu, Tools menu, etc looking for
>> where I can invoke the Debugger.  There was nothing in the README.
>> Finally I looked under the Keybindings preferences and saw there was
>> keybindings to run it, and there was no default keybindings selected.
>>
>> Point of that story is that *all* I needed was a few hints about what
>> the plugin added to the GUI and what I needed to do to invoke it.
>> Things like the new keybindings, their defaults, etc.  Personally,
>> after using some other IDEs, I would have expect a toolbar menu
>> button with "step into", "step out of", etc.  So I guess what I mean
>> is, if you add a keybinding, or a preference, or a menu item or
>> toolbar item, it should be documented.
>>
>> I don't mean to pick on the Debugger plugin, I think it's *really*
>> cool and I can appreciate that it's still under development, but this
>> is specifically what I was thinking of when I wrote that in my
>> previous message.
> Ah I see. So basicly what you refer to is having a suitable
> documentation at all with most important things as well as ensure there
> is a basic 'ingame' docu. Did I understand it correct?
>
I'm not sure what "'ingame' docu" means but what I mean is there should 
be a few minimal requirements, such as:
   - Tooltips on widgets added to the UI (where it makes sense)
   - A plugin_help() implementation, even if it just links to the README 
on plugins.geany.org
   - A README file with text content including
       - The purpose of the plugin, what it accomplishes, etc.
       - A list of keybindings that will be available when the plugin is 
loaded
       - A usage section explaining at least the basic way to use the plugin
       - A description of the new menu items, tool items, and so on 
introduced to the UI.

This is just some ideas...

Cheers,
Matthew Brush (codebrainz)



More information about the Devel mailing list