thoughts on Brooklyn docs

[Geoff Macartney <ge...@cloudsoftcorp.com>]

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

Re: thoughts on Brooklyn docs

[mohan kumar Muddana <mo...@gmail.com>]

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 <al...@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, <ri...@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
> > >>>>
> >
> >
>

Re: thoughts on Brooklyn docs

[Geoff Macartney <ge...@cloudsoftcorp.com>]

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 <al...@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, <ri...@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
> >>>>
>
>

Re: thoughts on Brooklyn docs

[Aled Sage <al...@gmail.com>]

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, <ri...@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
>>>>

Re: thoughts on Brooklyn docs

[mohan kumar Muddana <mo...@gmail.com>]

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, <ri...@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
> > >
> >
>

Re: thoughts on Brooklyn docs

[Geoff Macartney <ge...@cloudsoftcorp.com>]

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, <ri...@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
> >
>

Re: thoughts on Brooklyn docs

[Richard Downer <ri...@apache.org>]

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" <ge...@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
>

Re: thoughts on Brooklyn docs

[Rupinder Singh <ru...@gmail.com>]

Hi,
As a beginer user, I agree with Geoff ! We should have a lot of what he's
suggesting, especially some delineation of User, admin and developer. It'll
help!

Rupinder

On Fri, Apr 21, 2017 at 10:04 PM, 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
>