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.
I know its not possible for everybody and useful in every case, but I
did try to make on geanyLaTeX docu [1] what I'd like to have for every
plugin.
Cheers,
Frank
[1] http://frank.uvena.de/files/geany/manuals/geanylatex/geanylatex.html
_______________________________________________
Geany-devel mailing list
Geany-devel@uvena.de
http://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel
Cheers,
Matthew Brush (codebrainz)
_______________________________________________
Geany-devel mailing list
Geany-devel@uvena.de
http://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel
