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