<html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> </head> <body bgcolor="#FFFFFF" text="#000000"> Hi Laura, All, I'd like to follow up about the suggestion of a new site, thinking specifically about: * much of the existing content is out of date * there is a lot of 'formerly feedhenry) material to be published next year (eg mcp, sync) * the rendering toolchain is sub-optimal (in my POV) * big changes are happening anyway (now is the opportunity) However I'm not sure if this means revamping aerogear.org or the introduction of a new site docs.aerogear.org ? So, let me propose this, which is what I'd like to see: * Versioned docs for each component * A doc set for combining a set of components into a release * An asciidoc-first approach to the docs (altho I'd like to see markdown still supported for blogs/etc) With this in mind, I'm playing with asciibinder, for example, see the digger docs [1], this has the advantage: * it's what OpenShift uses * it's geared towards complex doc sets * it's geared to multiple version doc sets * it's lightweight and gathering some momentum (eg fedora are now using it) Maybe it's used for everything but the home page as per OS [2] Or maybe the existing aerogear.org lives on, and users only hit the asciibinder html at a lower level? WDYT? thanks, Paul [1] <a class="moz-txt-link-freetext" href="https://5-114535426-gh.circle-artifacts.com/0/home/circleci/docs/_preview/digger/latest/installation/digger-install-intro.html">https://5-114535426-gh.circle-artifacts.com/0/home/circleci/docs/_preview/digger/latest/installation/digger-install-intro.html</a> [2] <a class="moz-txt-link-freetext" href="https://docs.openshift.com/">https://docs.openshift.com/</a> <pre wrap=""> Date: Fri, 15 Dec 2017 13:56:57 +0000 From: Laura Fitzgerald <a class="moz-txt-link-rfc2396E" href="mailto:lfitzger@redhat.com"><lfitzger@redhat.com></a> To: AeroGear Developer Mailing List <a class="moz-txt-link-rfc2396E" href="mailto:aerogear-dev@lists.jboss.org"><aerogear-dev@lists.jboss.org></a>, <a class="moz-txt-link-abbreviated" href="mailto:feedhenry-dev@redhat.com">feedhenry-dev@redhat.com</a> Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of AeroGear.org Production Branch Message-ID: <a class="moz-txt-link-rfc2396E" href="mailto:CA+jLkhW2g4rrLfptKKUnAN5=LnMLksErnjXHnVXWVr7Fw9xcnA@mail.gmail.com"><CA+jLkhW2g4rrLfptKKUnAN5=LnMLksErnjXHnVXWVr7Fw9xcnA@mail.gmail.com></a> Content-Type: text/plain; charset="utf-8" Hi all, I had sent this email re improving the way that we pubish aerogear.org. Some may have seen it and replied but as there is some problems with aerogear-dev mailing and there has been some further discussions I wanted to reopen a conversation re Aerogear.org. With the move to the aerogear org there has been some conversation aroung an overhaul of the aerogear.org website. It was also suggested that we could go with a brand new site rather than rejigging the old site. I'm thinking that it would be worth having a discussion around how we would go about this. If anyone has particular interest in this and/or experience with the old site and existing tech and wants to open a proposal/discussion re tech stack, design, content etc I think it would be suitable to to do that via the proposals repo [1] or via some discussion here. I've been involved in adding some content recently with the Aerogear Digger Project and my vote would be for creating something new and shiny!!! Wdy guys t? [1] <a class="moz-txt-link-freetext" href="https://github.com/aerogear/proposals">https://github.com/aerogear/proposals</a> On Wed, Dec 6, 2017 at 11:07 AM, Laura Fitzgerald <a class="moz-txt-link-rfc2396E" href="mailto:lfitzger@redhat.com"><lfitzger@redhat.com></a> wrote: </pre> <blockquote type="cite" style="color: #000000;"> <pre wrap="">Hi all, I have recently gone through the process of publishing documentation for AeroGear Digger to aerogear.org. The process for adding docs for digger was as follows: - Make changes on Feature Branch over a period of time. - At some point merge lots of commits (difficult to review) from Feature Branch to master. - This publishes to staging.aerogear.org (build needs to be manually triggered in Jenkins) - At some point merge master (again with lots of commits) to production branch - This publishes to aerogear.org (build needs to be manually triggered) Out of this we attempted to improve the process by adding development steps to the README [1] outlining that -> each change should be verified on it's own -> merged to master -> and then merged to production removing the wait time and merges which involved lots of commits and changes. *I think there are a few things we can do to make this better. (simpler)* *1) How?* Remove the production branch (and related steps) altogether. *Why?* - All this documentation is done in the open. - All branches are visible to all users/developers. - staging.aerogear.org is not private so I don't see that we gain something by having this step. - Changes can be verified locally by building the website using the steps in the README [2] before being merged to master. *2) How?* Automate the publishing of the site *Why?* Right now the building of the site has to be triggered manually via a Jenkins instance on cloudbees. If we remove production and enforce that all changes are fully verified before being merged to master then we can automate that any new changes are published immediately once merged to master. *3) How?* Add some sort of versioning to the documentation. This could be in the form of tagging the repo once we have a release of a product. *Why?* If we are always publishing docs once a change is made to the product then we should version the documentation so we know which version of the docs matches older versions of the product. ~~~~~~~~~~~ I'm really interested in some feedback on this. Let me know what you think. Is there a better/simpler way to do it than I suggested? [1] <a class="moz-txt-link-freetext" href="https://github.com/aerogear/aerogear.org/blob/">https://github.com/aerogear/aerogear.org/blob/</a> master/README.md#development-steps [2] <a class="moz-txt-link-freetext" href="https://github.com/aerogear/aerogear.org/blob/">https://github.com/aerogear/aerogear.org/blob/</a> master/README.md#building -- LAURA FITZGERALD Red Hat Mobile <a class="moz-txt-link-rfc2396E" href="https://www.redhat.com/"><https://www.redhat.com/></a> Communications House, Cork Road Waterford City, Ireland X91NY33 <a class="moz-txt-link-abbreviated" href="mailto:lfitzger@redhat.com">lfitzger@redhat.com</a> IM: lfitzgerald <a class="moz-txt-link-rfc2396E" href="https://red.ht/sig"><https://red.ht/sig></a> </pre> </blockquote> <pre wrap=""> </pre> </body> </html>