Mailing-List: contact dev-help@brooklyn.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.apache.org
MIME-Version: 1.0
In-Reply-To: <CAE7C0PeZkXT3Wc4i__bD2M-fT8GdXjEMNAy7vnRbyb+e-y_yTw@mail.gmail.com>
References: <CAE7C0PdH0q-j+7GTVFEBm627S5YgDAO3hqZR7D8bm1aqgCU3Vw@mail.gmail.com>
 <CABQFKi0+KnS9xb9nQrNQAwCV7MEKJOk8LnAwkhpOQr=hPjU+AA@mail.gmail.com> <CAE7C0PeZkXT3Wc4i__bD2M-fT8GdXjEMNAy7vnRbyb+e-y_yTw@mail.gmail.com>
From: mohan kumar Muddana <mohanjune@gmail.com>
Date: Tue, 16 May 2017 01:23:51 +0530
Message-ID: <CAO+B9L6TYXv9RvU50QeZoB4cfkvyX4iCm418pgjvVCuxBZGkEg@mail.gmail.com>
Subject: Re: thoughts on Brooklyn docs
To: dev@brooklyn.apache.org
Content-Type: multipart/alternative; boundary="001a114494a00e161d054f956a32"
archived-at: Mon, 15 May 2017 19:53:57 -0000

--001a114494a00e161d054f956a32
Content-Type: text/plain; charset="UTF-8"

This was very high level when I created this when I was in Atos. Let me
know if this is of any help. I know the architecture has changed a bit
after that but basic flow remains the same.
Feel free to copy or let me know how to improve on that.


*https://github.com/mohanjune/brooklynlearnings/tree/master/docs
<https://github.com/mohanjune/brooklynlearnings/tree/master/docs>*
Thanks and regards
Mohan


On Thu, May 11, 2017 at 12:21 AM, Geoff Macartney <
geoff.macartney@cloudsoftcorp.com> wrote:

> 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
> > >
> >
>

--001a114494a00e161d054f956a32--