brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geoff Macartney <geoff.macart...@cloudsoftcorp.com>
Subject thoughts on Brooklyn docs
Date Fri, 21 Apr 2017 16:34:59 GMT
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