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 <
[email protected]> 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, <[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" <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
