[Geany-devel] Ideas on increasing quality of plugins
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:
>>> 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
- 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
- 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...
Matthew Brush (codebrainz)
More information about the Devel