hi all, Was just thinking some more about our docs, prompted by Thomas's great work on the redesign of the front page.
The update front page will be great, but I think it will still leave us with work to do on the overall structure and coverage of the docs in total. It feels to me like there are two things we need to do: - improve the structure, for clarity, and - fill in the main gap in the docs, namely the reference-level detail on each and every part of Brooklyn We need to think carefully about what we want in the docs and the intended audience. I think we maybe need a clearer separation between 'users' (people whose interest is the apps), 'admins' who have to manage Brooklyn, and 'developers' who'll work with the code. Not sure how it should be structured but maybe something like: 1. Learn more - 1 page overview of Brooklyn including example blueprint and a description of the lifecycle of deploying it 2. Getting started - how to get and run Brooklyn and deploy an app 3. User Guide - tutorials in more detail than getting started (cover DSL & wiring, clusters...) - plus explanations of all main aspects - some overlap with 'Reference' (see below) but more a how-to guide than a comprehensive reference. 4. Admin Guide 5. Developer Guide 6. Blueprint reference - comprehensive listing of all syntax and semantics of blueprints: including: blueprints versus catalog; explanations of basics such as entity/location/application, 'type', 'id', how brooklyn.config works, provisioning properties etc; composing catalog items; inheritance; every DSL method in detail; detailed description of every out-of-the-box entity; detailed description of every enricher, policy, etc; testing; ... and lots more What do you think? Geoff
