brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mohan kumar Muddana <mohanj...@gmail.com>
Subject Re: thoughts on Brooklyn docs
Date Tue, 16 May 2017 19:20:52 GMT
Thank you very much. Yes I guess so and I agree on that. I haven't gone
through the source code recently, hence would like to know if those have to
be updated based on any changes in the base framework.

Thanks and regards
Mohan

On Tue, May 16, 2017 at 1:14 PM, Geoff Macartney <
geoff.macartney@cloudsoftcorp.com> wrote:

> hi Mohan,
>
> those are great docs.  I agree, we could use them as inspiration to flesh
> out the "developers" section Aled mentions, turning it into an
> architectural overview.
>
> best
> Geoff
>
>
>
> On Tue, 16 May 2017 at 08:33 Aled Sage <aled.sage@gmail.com> wrote:
>
> > Thanks Mohan,
> >
> > That's helpful. Really useful to get different people's perspectives for
> > how to summarise the key points of Brooklyn!
> >
> > The diagrams are also interesting - good for communicating the control
> > flow to Brooklyn developers and new folk who want to contribute, or to
> > power-users who want to hook in at those levels. They feel more detailed
> > than a "normal user" of Brooklyn would want, so perhaps would be best
> > somewhere under the "developers" section, such as augmenting [1].
> >
> > Aled
> >
> > [1] http://brooklyn.apache.org/v/latest/dev/code/structure.html
> >
> >
> > On 15/05/2017 21:53, mohan kumar Muddana wrote:
> > > 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
> > >>>>
> >
> >
>

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