Was just chatting about docs with some colleagues and remembered this from Richard, which I thought was a great outline for what the docs should look like.
How about we make a start on reworking what's there with this as an initial guide to the endpoint, and see how it goes? On Fri, 21 Apr 2017, 21:44 Richard Downer, <[email protected]> wrote: > 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 > > >
