Hi, Yes there are some big improvements possible in this area.
As someone who has taken a bit of a back seat in using Apache Brooklyn for a while and has recently restarted actively developing blueprints, I've found that Brooklyn's features in this area have much improved over the last year or two, but the documentation has failed to keep up - many great features available to blueprint writers are either documented too briefly or in an illogical location, or not documented at all. I have been thinking that if I was to use my Copious Free Time to write a book about creating blueprints for Apache Brooklyn, it's table of contents would look something like this: Basic Ingredients - A simple server example - What the machine looks like - The software process lifecycle - Installing files - Sensors - Enrichers - Effectors Combining Parts - Multiple entities in one blueprint - References between entities - Latches - Child entities - Putting multiple entities on one server Catalog: the blueprint database - What is the catalog? - Looking inside the catalog - A simple blueprint into the catalog - Versions and updates - Parameters and configuration - Bundling resources with blueprints - A comprehensive example The Apache Brooklyn Blueprint Toolkit - Clusters - Java-based apps - [more standard Java entities] Policies for Active, Automated Management - Introduction to policies with the Service Restarter policy - [more policies] Blueprints for Microsoft Windows Server - [tbc] Writing Blueprints in Java - Depending on Apache Brooklyn: Maven - A simple Java blueprint - OSGI for versioning and dependency management - Enrichers - Policies Reference - Blueprint YAML - Apache Brooklyn DSL - Common ConfigKeys - Common Sensors - FreeMarker Template There would also be a separate manual covering the operational side of Brooklyn: installing and configuring, persistence and HA, configuring locations, managing the catalog, etc.. Then possibly a final user manual, which would probably be quite slim: just about how to use the UI and `br` client to work with blueprints already in the catalog, and examining running apps. My 2c. Richard. On 21 Apr 2017 17:36, "Geoff Macartney" <[email protected]> wrote: > 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 >
