[Grok-dev] Re: admin ui: displaying application docstrings

[Martijn Faassen]

Hey,

> Uli has a point. We can now change the tutorial and explain that the
> docstring of grok.Application subclasses will appear in the admin UI.
> Just because we didn't think of it when we wrote grokwiki doesn't mean
> it's not a good idea :). I think docstrings are actually a very neat way
> of getting some explanatory text into the UI.

I'm just worried about the dual purpose of docstring - code
documentation and something that shows up in the UI.

Now of course it makes sense to show docstrings when looking through
the documentation section of the admin UI. But the application
installation section is something that many others besides developers
will be confronted with, and we should consider what its goals are. Is
this for users and developers both, or for developers only?

If it's for users and developers both, I think we should consider not
using the dotted name for the applications anymore either, and not use
the docstring. This because two different demands will be made on the
docstring otherwise: UI and code documentation, and those often pull
in different ways. We should consider supporting menu registration,
where an application can say "I have this name, and this describes
what I do for UI purposes".

That said, we cannot make changes now, we need to think about this
some more. For the time being, let's stick with the dotted name and
the first line of the docstring. I just think that this is something
we may end up reconsidering as we consider the audience for this
screen further.

Regards,

Martijn