Idea: Improving documentation for bundled/extension plugins via "feature lists"

Since production Elgg sites tend to have many plugins, and many plugins extend the work of other plugins, I think Elgg should provide a better mechanism for delivering documentation to site admins (I want to steer clear of the discussion of help for end users in this thread).

Some plugin manifest/README files do a good job at providing a list of features provided therein. I'd like for the plugin page (and a separate admin/features page) to make these feature lists more prominently available, allow features to extend others, and to make it visually clear which plugin_id provides each. A feature could be added via the manifest, along with the feature it extends, if applicable.

On the admin Features page, a full hierarchy of features would be displayed, with "novel" features at the root level and branches showing feature extensions.

On the plugins page, each plugin would have a drop down able to display its features with some context: the parent and any descendants would be displayed if available.

I'll try to work up a mockup of what these might look like, but basically it would give admins, at a glance, the ability to see how each plugin affects their system.

Ideally an admin could export the feature tree (and plugin list) to plain text for more easily getting help in the community.

  • Steve, you are just an idea machine.  That sounds awesome and very useful.

  • The hope is to grease the wheels of documentation for plugin writers. Coming up with the manifest format (or some other method of declaring features) will be tough. E.g.

    Manifest for plugin_a:

    < feature name="do_x" />

    Manifest for plugin_b:

    < feature name="do_y">
        < alters>plugin_a/do_x< /alters>
    < /feature>
    < feature name="do_z" />

    Manifest for plugin_c:

    < feature name="do_k">
        < alters>plugin_b/do_y< /alters>
        < alters>plugin_a/do_x< /alters>
    < /feature> 

    In the above, plugin_c declares that its feature plugin_c/do_k (resolved via elgg_echo) alters plugin_b/do_y. But if that feature isn't found, place the feature under plugin_a/do_x. if this fallback mechanism isn't implemented, extending features would just show up at the root if their parent could not be found.
  • I like it - in a visual tree it would give a functional overview of the site as a whole.

    Of course the drawback is possibility of lazy devs still not documenting their plugins - leading to incomplete and therefore less useful trees...

  • Wondering if this could be automatically detected in some way, like we assume that a list of the actions provides a list of features we'd definitely want to mention, and parse the name and description out of the comments block at the top of the file. Alternatively to the comment block, we just use auto-generated language strings like action:blogs:create:label, action:blogs:create:description.

    I'm partial to extracting comments because that keeps documentation closer to the code, and the comments are useful even before we implement this special visualization.

  • We could definitely pull location/extension info out of the routes, actions, and views (like develop_tools/inspect does).

    Speaking of comment parsing, Phocco would be useful for turning an example plugin (or even one of the bundleds) into a tutorial.

Feedback and Planning

Feedback and Planning

Discussions about the past, present, and future of Elgg and this community site.