[feedhenry-dev] Suggestion/Discussion - Removal of AeroGear.org Production Branch
Paul Wright
pwright at redhat.com
Tue Dec 19 12:37:02 UTC 2017
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'?
>
> 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
> <mailto: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
> <http://www.keycloak.org/docs/latest/getting_started/index.html>
> https://docs.jboss.org/jbpm/release/7.4.1.Final/jbpm-docs/html_single
> <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
> <http://aerogear.org/> or the introduction of a new site
> docs.aerogear.org <http://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 <http://aerogear.org/sync>
> aerogear.org/digger <http://aerogear.org/digger>
>
> Example layout:
>
> 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
> <mailto: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
> <http://aerogear.org> or the introduction of a new site
> docs.aerogear.org <http://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 <http://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
> <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> <mailto:lfitzger at redhat.com>
> To: AeroGear Developer Mailing List<aerogear-dev at lists.jboss.org>
> <mailto:aerogear-dev at lists.jboss.org>,
> feedhenry-dev at redhat.com <mailto: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>
> <mailto: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 pubishaerogear.org <http://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 theaerogear.org <http://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
> <https://github.com/aerogear/proposals>
>
> On Wed, Dec 6, 2017 at 11:07 AM, Laura Fitzgerald<lfitzger at redhat.com> <mailto:lfitzger at redhat.com>
> wrote:
>
>> Hi all,
>>
>> I have recently gone through the process of publishing documentation for
>> AeroGear Digger toaerogear.org <http://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 tostaging.aerogear.org <http://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 toaerogear.org <http://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 <http://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/
>> <https://github.com/aerogear/aerogear.org/blob/>
>> master/README.md#development-steps
>> [2]https://github.com/aerogear/aerogear.org/blob/
>> <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 <mailto:lfitzger at redhat.com> IM: lfitzgerald
>> <https://red.ht/sig> <https://red.ht/sig>
>>
>>
>
> _______________________________________________
> feedhenry-dev mailing list
> feedhenry-dev at redhat.com <mailto:feedhenry-dev at redhat.com>
> https://www.redhat.com/mailman/listinfo/feedhenry-dev
> <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 <mailto:feedhenry-dev at redhat.com>
> https://www.redhat.com/mailman/listinfo/feedhenry-dev
> <https://www.redhat.com/mailman/listinfo/feedhenry-dev>
>
>
>
>
> --
> David Martin
> Red Hat Mobile
> Twitter: @irldavem
> IRC: @irldavem (feedhenry, mobile-internal)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/feedhenry-dev/attachments/20171219/0c8ce290/attachment.htm>
-------------- 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://listman.redhat.com/archives/feedhenry-dev/attachments/20171219/0c8ce290/attachment.png>
More information about the feedhenry-dev
mailing list