[aerogear-dev] Aerogear documentation navigation

[Paul Wright]

Excuse my ignorance, but I've been caught a few times by the docs navigation on aerogear.org, specifically, I click 'Docs' and then cannot find any guides:

Ok, it does say this is 'API Doc and Specs' in low contrast text and there are links to 'Guides' if I scroll to the bottom of the page, but is this how we want it to work?

That's where my ignorance comes in, is there some plan here that I'm not aware of, or should I just go ahead and make a PR?

thanks,
Paul

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

[Jose Miguel Gallas Olmedo]

I think the problem is "Doc" means "Reference" and the actual documentation is under "getting started". But it should be more accessible, maybe we should make "Docs" a dropdown with "Reference" and "Guides" inside.

On 11 August 2017 at 12:26, Paul Wright <[hidden email]> wrote:

Excuse my ignorance, but I've been caught a few times by the docs navigation on aerogear.org, specifically, I click 'Docs' and then cannot find any guides:

Ok, it does say this is 'API Doc and Specs' in low contrast text and there are links to 'Guides' if I scroll to the bottom of the page, but is this how we want it to work?

That's where my ignorance comes in, is there some plan here that I'm not aware of, or should I just go ahead and make a PR?

thanks,
Paul

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

[Matthias Wessendorf]

Hey Paul,

feel free to send a PR for this. Thx!

On Fri, Aug 11, 2017 at 12:26 PM, Paul Wright <[hidden email]> wrote:

Excuse my ignorance, but I've been caught a few times by the docs navigation on aerogear.org, specifically, I click 'Docs' and then cannot find any guides:

Ok, it does say this is 'API Doc and Specs' in low contrast text and there are links to 'Guides' if I scroll to the bottom of the page, but is this how we want it to work?

That's where my ignorance comes in, is there some plan here that I'm not aware of, or should I just go ahead and make a PR?

thanks,
Paul

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

--

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

[Summers Pittman]

Or feel free to make suggestions, the reference docs and guides probably need a fresh critical eye anyway.

On Fri, Aug 11, 2017 at 7:29 AM, Matthias Wessendorf <[hidden email]> wrote:

Hey Paul,

feel free to send a PR for this. Thx!

On Fri, Aug 11, 2017 at 12:26 PM, Paul Wright <[hidden email]> wrote:

Excuse my ignorance, but I've been caught a few times by the docs navigation on aerogear.org, specifically, I click 'Docs' and then cannot find any guides:

Ok, it does say this is 'API Doc and Specs' in low contrast text and there are links to 'Guides' if I scroll to the bottom of the page, but is this how we want it to work?

That's where my ignorance comes in, is there some plan here that I'm not aware of, or should I just go ahead and make a PR?

thanks,
Paul

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

--

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

[Paul Wright]

Thanks,

I could just create a PR for this particular issue, or ...

how about a refresh/doc review, and replacing jekyll with asciibinder:

* Allow us publish multiple branches of docs (releases)

* Allow contributors familiar with asciibinder, eg openshift contributors  to contribute

* Allow me sync with downstream docs in a consistent process (distros)

Ok, that last one is just for me, but it should be possible to keep the aerogear look and feel, but provide a better experience for users. asciibinder is designed by red hatters for multiple distros of documentation, and is what openshift use:

https://docs.openshift.com/container-platform/3.6/welcome/index.html

Anyone object if we go down this road? (again, there might be unique feature of the current website that I'm not familiar with)

thanks,

Paul

On 08/11/2017 04:16 PM, Summers Pittman wrote:

Or feel free to make suggestions, the reference docs and guides probably need a fresh critical eye anyway.

On Fri, Aug 11, 2017 at 7:29 AM, Matthias Wessendorf <[hidden email]> wrote:

Hey Paul,

feel free to send a PR for this. Thx!

On Fri, Aug 11, 2017 at 12:26 PM, Paul Wright <[hidden email]> wrote:

Excuse my ignorance, but I've been caught a few times by the docs navigation on aerogear.org, specifically, I click 'Docs' and then cannot find any guides:

Ok, it does say this is 'API Doc and Specs' in low contrast text and there are links to 'Guides' if I scroll to the bottom of the page, but is this how we want it to work?

That's where my ignorance comes in, is there some plan here that I'm not aware of, or should I just go ahead and make a PR?

thanks,
Paul

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

--

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev

_______________________________________________
aerogear-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/aerogear-dev