[aerogear-dev] [feedhenry-dev] Suggestion/Discussion - Removal of AeroGear.org Production Branch

Tue Dec 19 07:49:18 EST 2017

On 19 December 2017 at 12:37, Paul Wright <pwright at redhat.com> wrote:

> Hi,
> On 12/19/2017 09:46 AM, David Martin wrote:
>
> I like the idea of a custom landing page, and using asciibinder thereafter
> for all docs.
> The landing page would initially function as a gateway to the upstream
> docs, and any other upstream content (e.g. contributing guide)
> Adding downstream or other version of docs could come later.
>
> @Paul, @Laura What would be involved in converting the existing Aerogear
> docs into asciidoc and getting them working with asciibinder?
>
> Good news! Digger doc is already in asciidoc (altho some work required, eg
> file suffix, include syntax is non-standard)
> re. Push, I'm thinking this is the major piece? https://aerogear.org/docs/
> unifiedpush/ups_userguide/index/
>
> I'll convert that to asciidoc as a first step in this journey
>
> It would make sense to leave behind docs for anything deprecated or no
> longer maintained.
>
> How would that work? a link to 'Old site'?
>
I'm not sure, but I would love to avoid a scenario where 2 sites exist.

To give an example of why I don't like that, take Keycloak Docs.

I did a google search for Keycloak Identiy Brokering and get a link to
https://keycloak.gitbooks.io/documentation/server_admin/topics/identity-broker.html
However, thats the old site, which just gives a link to the new site.
What makes it worse is the link to the new site brings me to a landing page
where I need to try find what I'm looking for again.
http://www.keycloak.org/documentation.html.

Awful user experience.

>
>
>
> Updating any docs (e.g.  UPS) could be a task for after the initial
> 'getting things working with asciibinder'.
> Similarly, moving Sync docs could be a task after the initial work.
>
>
> On 19 December 2017 at 09:34, Wojciech Trocki <wtrocki at redhat.com> wrote:
>
>> +1 for kicking out some investigations.
>> Let me know if you need something specific.
>> I see that most of the JBoos products now using ascidocs based
>> documentation.
>>
>> For example:
>> http://www.keycloak.org/docs/latest/getting_started/index.html
>> https://docs.jboss.org/jbpm/release/7.4.1.Final/jbpm-docs/html_single
>>
>>
>> > However I'm not sure if this means  revamping  aerogear.org or the
>> introduction of a new site docs.aerogear.org ?
>>
>> Aerogear is project aggregator website so aproach will need to be
>> different than when building webpage for single project.
>> IMHO best is to refresh aerogear webpage layout to support project
>> subpages. For example
>>
>> aerogear.org/sync
>> aerogear.org/digger
>>
>> Example layout:
>>
>> [image: Inline image 1]
>> Then each of this subpages can have general information, links to
>> documentation, supported versions etc.
>> This aproach is really common for open source projects aggregators.
>>
>>
>> On Mon, Dec 18, 2017 at 8:04 PM, Paul Wright <pwright at redhat.com> wrote:
>>
>>> 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] https://5-114535426-gh.circle-artifacts.com/0/home/circleci/
>>> docs/_preview/digger/latest/installation/digger-install-intro.html
>>>
>>> [2] https://docs.openshift.com/
>>>
>>> Date: Fri, 15 Dec 2017 13:56:57 +0000
>>> From: Laura Fitzgerald <lfitzger at redhat.com> <lfitzger at redhat.com>
>>> To: AeroGear Developer Mailing List <aerogear-dev at lists.jboss.org> <aerogear-dev at lists.jboss.org>,
>>> 	feedhenry-dev at redhat.com
>>> Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
>>> 	AeroGear.org	Production Branch
>>> Message-ID:
>>> 	<CA+jLkhW2g4rrLfptKKUnAN5=LnMLksErnjXHnVXWVr7Fw9xcnA at mail.gmail.com> <CA+jLkhW2g4rrLfptKKUnAN5=LnMLksErnjXHnVXWVr7Fw9xcnA at mail.gmail.com>
>>> 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] https://github.com/aerogear/proposals
>>>
>>> On Wed, Dec 6, 2017 at 11:07 AM, Laura Fitzgerald <lfitzger at redhat.com> <lfitzger at redhat.com>
>>> wrote:
>>>
>>>
>>> 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] https://github.com/aerogear/aerogear.org/blob/
>>> master/README.md#development-steps
>>> [2] https://github.com/aerogear/aerogear.org/blob/
>>> master/README.md#building
>>> --
>>>
>>> LAURA FITZGERALD
>>>
>>> Red Hat Mobile <https://www.redhat.com/> <https://www.redhat.com/>
>>>
>>> Communications House, Cork Road
>>>
>>> Waterford City, Ireland X91NY33
>>> lfitzger at redhat.com    IM: lfitzgerald<https://red.ht/sig> <https://red.ht/sig>
>>>
>>>
>>> _______________________________________________
>>> feedhenry-dev mailing list
>>> feedhenry-dev at redhat.com
>>> https://www.redhat.com/mailman/listinfo/feedhenry-dev
>>>
>>>
>>
>>
>> --
>>
>> WOJCIECH TROCKI
>>
>> Red Hat Mobile <https://www.redhat.com/>
>>
>> IM: wtrocki
>> <https://red.ht/sig>
>>
>> _______________________________________________
>> feedhenry-dev mailing list
>> feedhenry-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/feedhenry-dev
>>
>>
>
>
> --
> David Martin
> Red Hat Mobile
> Twitter: @irldavem
> IRC: @irldavem (feedhenry, mobile-internal)
>
>
>

-- 
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (feedhenry, mobile-internal)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20171219/9d6f08ea/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screen Shot 2017-12-19 at 9.28.29 AM.png
Type: image/png
Size: 300684 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/aerogear-dev/attachments/20171219/9d6f08ea/attachment-0001.png 