On Fri, 11 Mar 2011 15:36:50 -0800 Matthew Brush matthewbrush@gmail.com wrote:
On 03/11/11 14:43, Frank Lanitz wrote:
On Wed, 09 Mar 2011 07:27:06 -0800 Matthew Brushmatthewbrush@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' ;)