Alex, Great proposal.
In my suggestion I had split "community" into two top level items, "community" and "developers". The guides to making code contributions, accessing CI and snapshot builds, etc. were present under the "developers" menu. The "community" header was left for items about how our users (non-contributing, non-developing) can contact us, report bugs, etc. As I expect that over time we will have more "users" than "developers" I would prefer to see that they are not lumped together in the same group. WDYT? Richard. On 20 August 2014 14:16, Alex Heneveld <[email protected]> wrote: > > Richard, All - > > Great start. I agree with most of your points. The biggest gap I see > however is that the user guide is way too hard to find anything. It needs a > massive refactoring: smaller pages, better organisation, and simplified > getting started. > > The priorities I've gone for are: > * new users can get started easily and get involved > * existing users and developers can quickly find what they need > * new non-users can clearly understand what we do and the value > * existing users and developers can add new content > > I've taken your outline Richard, which I really like, and expanded it, along > with a proposed new user guide structure to try to help the above. PDF > attached. The commentable source version is online at [1]. > > Everyone please let us know your thoughts! > > I'd love it if we can act on this quickly, and get it to a point where > incremental improvements can be made iteratively. > > Best > Alex > > > [1] > https://docs.google.com/a/cloudsoftcorp.com/document/d/1GyK-raCf632LORv04SnsbmPwlZPwZLDi64SZ7k7AuM8/edit > > > On 12/08/2014 12:29, Richard Downer wrote: >> >> All, >> >> Apache Brooklyn currently has a website which covers the requirement >> of "minimum viable website" targeted at visitors who are unfamiliar >> with our project, an additional few pages about how to commit, and is >> sufficiently aesthetically pleasing. >> >> It does however require a lot more content than "minimum viable for >> new visitors". A lot of useful content is buried in the user guide >> located at https://brooklyn.incubator.apache.org/v/0.7.0-M1/, which >> needs to be moved out of the user guide an into the main website, and >> then the user guide cleaned up to remove redundant information. >> >> I'd like to kick off a discussion about what content the primary >> website should have and how it should be organised. I'd like to start >> by proposing this top-level organisation: >> >> * learn more >> * download >> * get started >> * documentation >> * community >> * developers [NEW] >> >> i.e. the same as the current organisation, with the addition of a >> "developers" section. >> >> We should then start building addition content under each section, >> re-using content from the old users guide as much as possible. I >> suggest: >> >> * learn more >> -- introduction [no change] >> -- core entities >> -- glossary >> * download [no change] >> * get started [no change] >> * documentation >> -- user guide >> -- locations [guide to commonly-used locations] >> -- faq >> -- ... >> * community >> -- mailing lists >> -- irc >> -- issue tracker >> * developers >> -- how to contribute >> -- accessing snapshot builds >> -- link to CI >> -- guide for committers >> -- ... >> >> With regards to the user guide - this is currently organised into the >> sections Start, Using Brooklyn, Contributing, License and Meta. >> >> *Start* overlaps with the "get started" section of the website - in >> fact, this is where much of the content was taken from. This can be >> removed from the user guide (after ensuring that all relevant >> information is indeed now present on the main website). >> >> *Using Brooklyn* is the main user guide so this should obviously stay >> where it is (and become the landing page for the user guide) >> >> *Contributing* contains some sections that will likely be version >> specific (such as how to write an entity) and so should stay in the >> user guide. But much of the content is version-agnostic, such as how >> to build using Maven and how to configure your IDE. Therefore, some of >> this content should be moved to the *developers* section of the main >> website. >> >> *License* and *Meta* are now largely redundant by way of our move into >> The ASF, and the remaining useful information should already be >> present on the main website. This can be removed from the user guide >> (after ensuring that all relevant information is indeed now present on >> the main website). >> >> Any comments on this? I will (inbetween other tasks on my plate e.g. a >> release is an important thing I should be doing!) prototype some of >> this organisation and post a link for anybody who would like to see >> it. In particular I am slightly concerned that the addition of another >> top-level heading for "developers" may make the header a bit crowded, >> but I'm not sure what else I could remove instead. >> >> Cheers >> >> Richard. > >
