Revision of HiveMind documentation

Feedback from HiveMind community advises that the HiveMind documentation could need some improval.

Problems to address in a revision of HiveMind documentation:

  • A clear guide how to read documentation is missing. Documentation is too clustered
  • Example-Code: The page Example-Code shows the output of an ant script only.
  • The start page is a mixture of a basic tutorial and project status information.
  • Chapter 'Why should you use HiveMind' starts with task 'Log method entry and exit'. There are better reasons. The 'HiveMind approach' isn't always linked with an example
  • Chapter 'Bootstrapping the registry' is a kind of 'how to start' tutorial. Awkward name IMHO. The content and output of the 'build examples' ant-script aren't really helpful.
  • A lot of the chapters under 'Tutorials and information' are quite advanced material (like localization, multi-threading, overriding services etc.).

Missing examples/doc:

  • Recommended Usage and registry bootstrapping in Web-Application, Thin-Client, Webstart, J2EE Application Server
  • Lifecycles: Naming convention 'initializeService', BuilderFactory: property initialize-method, RegistryShutdownListener, Discardable
  • Implementation and usage of interceptors
  • ServiceModels
  • Submodules
  • Events
  • Registry construction from a XML descriptor other than META-INF\hivemodule.xml
  • More Dependency injection examples. Setter + constructor-injection, autowiring
  • Algorithms used for autowiring
  • Datasources
  • POJOs as services

Suggested new site structure:

  • Welcome
    • Short Description, Guide to doc and tutorials
    • Status
    • Upgrade Warnings
    • Acknowledgements
  • Tutorials and Information
    • Quickstart
    • Manual
      • Why should you use HiveMind
      • Very Simple Example
      • Services
        • Construction/Wiring
        • Service Models
        • Life Cycle
        • Interceptors
        • Events
        • Pojo Services
      • Configurations
      • Modules
      • Usage scenarios
        • Web Application
        • Application Server
        • Web Start
      • Groovy support
      • Internationalization
    • Examples
      • Links to examples in manual
      • Additional Examples
        • Registry construction
        • Datasources
        • ..
    • Additional Topics
      • IoC Background
      • ...

Everything on this page sounds good. The only comment I'd like to add is that the documentation needs to read more like a book and less like a random bunch of links. The spring documentation achieves this fairly well.

  • No labels