[Geany-devel] Ideas on increasing quality of plugins

[Frank Lanitz]

On Fri, 11 Mar 2011 15:36:50 -0800
Matthew Brush <matthewbrush at gmail.com> wrote:

> 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...

Yepp, that's what I understood under 'ingame' ;)


-- 
http://frank.uvena.de/en/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.geany.org/pipermail/devel/attachments/20110312/f9970d73/attachment.pgp>