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.