Howdy again I was thinking on how should we organize our site + generated docs. We've been talking on hosting api.aerogear.org, but Kris remembered me of how important is to have separated -dev and -stable docs. So my first proposal for this org is: aerogear.org for our production site - generated from our 'production' branch staging.aerogear.org the same for 'staging' branch

api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev?

IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions)

thoughts? -- qmx _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Sep 5, 2012, at 6:09 AM, Douglas Campos <qmx(a)qmx.me&gt; wrote: > Howdy again > > I was thinking on how should we organize our site + generated docs. We've been talking on hosting api.aerogear.org, but Kris remembered me of how important is to have separated -dev and -stable docs. > > So my first proposal for this org is: > > aerogear.org for our production site - generated from our 'production' branch > staging.aerogear.org the same for 'staging' branch +1 for this. Only suggestion I would make is that there is no need for a staging branch. We could just use master as the staging branch.

> > api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. > > thoughts? > > -- qmx > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

>> api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) > > I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. Do you really want to host every 'alpha', 'beta' etc online ? For major releases I can see that, but IMO when alpha2 is released, I am not sure if there is really need to host alpha1..

> And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. >> I like the linking from the W3C, where they link to both 'published' and 'dev' spec -M >> thoughts? >> >> -- qmx >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev -- Matthias Wessendorf blog: http://matthiaswessendorf.wordpress.com/ sessions: http://www.slideshare.net/mwessendorf twitter: http://twitter.com/mwessendorf _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Wed, Sep 5, 2012 at 2:06 PM, Kris Borchers <kris(a)redhat.com&gt; wrote: > > On Sep 5, 2012, at 6:52 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: > >>>> api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) >>> >>> I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. >> >> >> Do you really want to host every 'alpha', 'beta' etc online ? >> For major releases I can see that, but IMO when alpha2 is released, I >> am not sure if there is really need to host alpha1.. > > No, sorry I wasn't clear. Just older final versions. I think alpha, beta, etc. should not be kept. +1

>> >> >>> And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. >>>> >> >> I like the linking from the W3C, where they link to both 'published' >> and 'dev' spec >> >> -M >> >> >> >> >>>> thoughts? >>>> >>>> -- qmx >>>> >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> >> -- >> Matthias Wessendorf >> >> blog: http://matthiaswessendorf.wordpress.com/ >> sessions: http://www.slideshare.net/mwessendorf >> twitter: http://twitter.com/mwessendorf >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev -- Matthias Wessendorf blog: http://matthiaswessendorf.wordpress.com/ sessions: http://www.slideshare.net/mwessendorf twitter: http://twitter.com/mwessendorf _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Sep 5, 2012, at 9:36 AM, Jay Balunas wrote: > > On Sep 5, 2012, at 8:17 AM, Matthias Wessendorf wrote: > >> On Wed, Sep 5, 2012 at 2:06 PM, Kris Borchers <kris(a)redhat.com&gt; wrote: >>> >>> On Sep 5, 2012, at 6:52 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: >>> >>>>>> api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) >>>>> >>>>> I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. >>>> >>>> >>>> Do you really want to host every 'alpha', 'beta' etc online ? >>>> For major releases I can see that, but IMO when alpha2 is released, I >>>> am not sure if there is really need to host alpha1.. >>> >>> No, sorry I wasn't clear. Just older final versions. I think alpha, beta, etc. should not be kept. >> >> >> +1 > > +1 - they would be accessible from git repo's if needed. > > I like defining rules for things like this to make it clear. > > api.aerogear.org/<subproject>/ > * Always host the last stable release docs for the overall AeroGear project No Jay, we would have a landing page that says stable/development and a list of versions. so api.aerogear.org/<subproject>/<version>

helps keeping things simple > * If there is no stable release yet (i.e. not at 1.0.Final+ yet) it hosts most recent AeroGear milestone release docs > * Note - this mean that after 1.0.Final future milestone docs (i.e. 2.0.0.M2) would need to be located somewhere else > > What would the other rules look like? > > > >> >> >> >>>> >>>> >>>>> And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. >>>>>> >>>> >>>> I like the linking from the W3C, where they link to both 'published' >>>> and 'dev' spec >>>> >>>> -M >>>> >>>> >>>> >>>> >>>>>> thoughts? >>>>>> >>>>>> -- qmx >>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> aerogear-dev mailing list >>>>>> aerogear-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>> >>>>> >>>>> _______________________________________________ >>>>> aerogear-dev mailing list >>>>> aerogear-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> >>>> -- >>>> Matthias Wessendorf >>>> >>>> blog: http://matthiaswessendorf.wordpress.com/ >>>> sessions: http://www.slideshare.net/mwessendorf >>>> twitter: http://twitter.com/mwessendorf >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> >> -- >> Matthias Wessendorf >> >> blog: http://matthiaswessendorf.wordpress.com/ >> sessions: http://www.slideshare.net/mwessendorf >> twitter: http://twitter.com/mwessendorf >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev -- qmx _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Sep 5, 2012, at 9:45 AM, Jay Balunas wrote: > > On Sep 5, 2012, at 8:39 AM, Douglas Campos wrote: > >> >> On Sep 5, 2012, at 9:36 AM, Jay Balunas wrote: >> >>> >>> On Sep 5, 2012, at 8:17 AM, Matthias Wessendorf wrote: >>> >>>> On Wed, Sep 5, 2012 at 2:06 PM, Kris Borchers <kris(a)redhat.com&gt; wrote: >>>>> >>>>> On Sep 5, 2012, at 6:52 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: >>>>> >>>>>>>> api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) >>>>>>> >>>>>>> I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. >>>>>> >>>>>> >>>>>> Do you really want to host every 'alpha', 'beta' etc online ? >>>>>> For major releases I can see that, but IMO when alpha2 is released, I >>>>>> am not sure if there is really need to host alpha1.. >>>>> >>>>> No, sorry I wasn't clear. Just older final versions. I think alpha, beta, etc. should not be kept. >>>> >>>> >>>> +1 >>> >>> +1 - they would be accessible from git repo's if needed. >>> >>> I like defining rules for things like this to make it clear. >>> >>> api.aerogear.org/<subproject>/ >>> * Always host the last stable release docs for the overall AeroGear project >> No Jay, we would have a landing page that says stable/development and a list of versions. so api.aerogear.org/<subproject>/<version> > > Sure, the base document landing page would have api, guides, contributing, development sections with the direct links. > > Wouldn't you want the link to the most recent stable docs to be the shortest? Also to help with general maintenance (i.e. site links) it is important that we provide a static link to the latest stable docs, and latest dev/staging docs. I've thought on symlinks for those stable -> 3.0.0 / dev -> 8.0.0.M256

> >> >> helps keeping things simple >>> * If there is no stable release yet (i.e. not at 1.0.Final+ yet) it hosts most recent AeroGear milestone release docs >>> * Note - this mean that after 1.0.Final future milestone docs (i.e. 2.0.0.M2) would need to be located somewhere else I basically want to avoid this altogether - for the sake of consistence, and keeping links valid

>>> >>> What would the other rules look like? >>> >>> >>> >>>> >>>> >>>> >>>>>> >>>>>> >>>>>>> And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. >>>>>>>> >>>>>> >>>>>> I like the linking from the W3C, where they link to both 'published' >>>>>> and 'dev' spec >>>>>> >>>>>> -M >>>>>> >>>>>> >>>>>> >>>>>> >>>>>>>> thoughts? >>>>>>>> >>>>>>>> -- qmx >>>>>>>> >>>>>>>> >>>>>>>> _______________________________________________ >>>>>>>> aerogear-dev mailing list >>>>>>>> aerogear-dev(a)lists.jboss.org >>>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>>>> >>>>>>> >>>>>>> _______________________________________________ >>>>>>> aerogear-dev mailing list >>>>>>> aerogear-dev(a)lists.jboss.org >>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> Matthias Wessendorf >>>>>> >>>>>> blog: http://matthiaswessendorf.wordpress.com/ >>>>>> sessions: http://www.slideshare.net/mwessendorf >>>>>> twitter: http://twitter.com/mwessendorf >>>>>> >>>>>> _______________________________________________ >>>>>> aerogear-dev mailing list >>>>>> aerogear-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>> >>>>> >>>>> _______________________________________________ >>>>> aerogear-dev mailing list >>>>> aerogear-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> >>>> -- >>>> Matthias Wessendorf >>>> >>>> blog: http://matthiaswessendorf.wordpress.com/ >>>> sessions: http://www.slideshare.net/mwessendorf >>>> twitter: http://twitter.com/mwessendorf >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> -- qmx >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev -- qmx _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Sep 5, 2012, at 8:39 AM, Douglas Campos wrote: > > On Sep 5, 2012, at 9:36 AM, Jay Balunas wrote: > >> >> On Sep 5, 2012, at 8:17 AM, Matthias Wessendorf wrote: >> >>> On Wed, Sep 5, 2012 at 2:06 PM, Kris Borchers <kris(a)redhat.com&gt; wrote: >>>> >>>> On Sep 5, 2012, at 6:52 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: >>>> >>>>>>> api.aerogear.org/<subproject>/ for API docs? how should we differentiate from stable and dev? IMHO we need to have consistence across the projects, but at the same time I'm out of ideas apart from api.aerogear.org/aerogear-js/1.0.0.Alpha1/ (version component is the last, being 'current' or 'dev' the current versions) >>>>>> >>>>>> I am also +1 for this organization. That way, we can keep all old docs live for those using older version and use it as a way of informing user of no longer supporting versions with messaging on the docs. >>>>> >>>>> >>>>> Do you really want to host every 'alpha', 'beta' etc online ? >>>>> For major releases I can see that, but IMO when alpha2 is released, I >>>>> am not sure if there is really need to host alpha1.. >>>> >>>> No, sorry I wasn't clear. Just older final versions. I think alpha, beta, etc. should not be kept. >>> >>> >>> +1 >> >> +1 - they would be accessible from git repo's if needed. >> >> I like defining rules for things like this to make it clear. >> >> api.aerogear.org/<subproject>/ >> * Always host the last stable release docs for the overall AeroGear project > No Jay, we would have a landing page that says stable/development and a list of versions. so api.aerogear.org/<subproject>/<version> Sure, the base document landing page would have api, guides, contributing, development sections with the direct links. Wouldn't you want the link to the most recent stable docs to be the shortest? Also to help with general maintenance (i.e. site links) it is important that we provide a static link to the latest stable docs, and latest dev/staging docs.

> > helps keeping things simple >> * If there is no stable release yet (i.e. not at 1.0.Final+ yet) it hosts most recent AeroGear milestone release docs >> * Note - this mean that after 1.0.Final future milestone docs (i.e. 2.0.0.M2) would need to be located somewhere else >> >> What would the other rules look like? >> >> >> >>> >>> >>> >>>>> >>>>> >>>>>> And we can use that same messaging to inform users that they are looking at the dev version which is subject to change and shouldn't be used in production. >>>>>>> >>>>> >>>>> I like the linking from the W3C, where they link to both 'published' >>>>> and 'dev' spec >>>>> >>>>> -M >>>>> >>>>> >>>>> >>>>> >>>>>>> thoughts? >>>>>>> >>>>>>> -- qmx >>>>>>> >>>>>>> >>>>>>> _______________________________________________ >>>>>>> aerogear-dev mailing list >>>>>>> aerogear-dev(a)lists.jboss.org >>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> aerogear-dev mailing list >>>>>> aerogear-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>> >>>>> >>>>> >>>>> -- >>>>> Matthias Wessendorf >>>>> >>>>> blog: http://matthiaswessendorf.wordpress.com/ >>>>> sessions: http://www.slideshare.net/mwessendorf >>>>> twitter: http://twitter.com/mwessendorf >>>>> >>>>> _______________________________________________ >>>>> aerogear-dev mailing list >>>>> aerogear-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> >>> -- >>> Matthias Wessendorf >>> >>> blog: http://matthiaswessendorf.wordpress.com/ >>> sessions: http://www.slideshare.net/mwessendorf >>> twitter: http://twitter.com/mwessendorf >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > -- qmx > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev