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