Suggestion/Discussion - Removal of AeroGear.org Production Branch

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Suggestion/Discussion - Removal of AeroGear.org Production Branch

pwright
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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



  


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion/Discussion - Removal of AeroGear.org Production Branch

Wojciech Trocki
+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:


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 

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 <[hidden email]> 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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



  

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion/Discussion - Removal of AeroGear.org Production Branch

David Martin
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?
It would make sense to leave behind docs for anything deprecated or no longer maintained.

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 <[hidden email]> 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:


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 

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 <[hidden email]> 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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



  

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (feedhenry, mobile-internal)

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion/Discussion - Removal of AeroGear.org Production Branch

Wojciech Trocki
+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:

> 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 


Example layout:

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 Tue, Dec 19, 2017 at 9:46 AM, David Martin <[hidden email]> 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?
It would make sense to leave behind docs for anything deprecated or no longer maintained.

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 <[hidden email]> 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:


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 

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 <[hidden email]> 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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



  

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (feedhenry, mobile-internal)



--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion/Discussion - Removal of AeroGear.org Production Branch

pwright
In reply to this post by David Martin

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 <[hidden email]> 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:


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 

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 <[hidden email]> 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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (feedhenry, mobile-internal)


_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion/Discussion - Removal of AeroGear.org Production Branch

David Martin


On 19 December 2017 at 12:37, Paul Wright <[hidden email]> 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.

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 <[hidden email]> 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:


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 

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 <[hidden email]> 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 [hidden email]
To: AeroGear Developer Mailing List [hidden email],
	[hidden email]
Subject: Re: [feedhenry-dev] Suggestion/Discussion - Removal of
	AeroGear.org	Production Branch
Message-ID:
	[hidden email]
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 [hidden email]
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/>

Communications House, Cork Road

Waterford City, Ireland X91NY33

[hidden email]    IM: lfitzgerald
<https://red.ht/sig>



_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki


_______________________________________________
feedhenry-dev mailing list
[hidden email]
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)

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev