brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geoff Macartney <geoff.macart...@cloudsoftcorp.com>
Subject Re: thoughts on Brooklyn docs
Date Wed, 10 May 2017 18:51:51 GMT
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, <richard@apache.org> 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" <geoff.macartney@cloudsoftcorp.com
> >
> 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
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message