You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@qpid.apache.org by Justin Ross <jr...@apache.org> on 2013/05/10 18:39:17 UTC
Website update 4
Update:
http://people.apache.org/~jross/transom/2013-05-10/
Previous versions:
http://people.apache.org/~jross/transom/2013-04-16/
http://people.apache.org/~jross/transom/2013-04-03/
http://people.apache.org/~jross/transom/2013-03-26/
http://people.apache.org/~jross/transom/2013-03-13/
Head version, for following things as they change:
http://people.apache.org/~jross/transom/head/
The source code and README:
https://github.com/ssorj/transom
Some bigger changes:
- Added scripts to generate release notes
- Added link to EAP 6 instructions in JCA page
- Added QMF api doc
- Add pdfs to book-generation scripts
- Updated the messenger doc snapshot
- Added messenger and protocol engine API doc in C, python, and java
- Added messenger examples in many languages
- Added make target and instructions for publishing content
- Improved the developer center
- Added 0.22 release content
- Overhauled the scripts for generating release content
- Added jms examples
To better show the proposed launch state, I've made 0.22 the current
release in the preview site. As a result, some of the links won't
work because they point to things (such as a release tag) that don't
exist yet.
I'd like to hold a vote in about a week on replacing our current
website. I'll have time for another update in the meantime, so please
let me know about any changes you'd like to see. In particular, take
a pass through the component page for the parts of Qpid you are
familiar with. I'd love to get some detailed corrections and
refinements.
Thanks!
Justin
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by Alan Conway <ac...@redhat.com>.
On 05/14/2013 04:45 AM, Gordon Sim wrote:
> On 05/10/2013 05:39 PM, Justin Ross wrote:
>> Update:
>> http://people.apache.org/~jross/transom/2013-05-10/
>> Previous versions:
>> http://people.apache.org/~jross/transom/2013-04-16/
>> http://people.apache.org/~jross/transom/2013-04-03/
>> http://people.apache.org/~jross/transom/2013-03-26/
>> http://people.apache.org/~jross/transom/2013-03-13/
>> Head version, for following things as they change:
>> http://people.apache.org/~jross/transom/head/
>> The source code and README:
>> https://github.com/ssorj/transom
>>
>> Some bigger changes:
>>
>> - Added scripts to generate release notes
>> - Added link to EAP 6 instructions in JCA page
>> - Added QMF api doc
>> - Add pdfs to book-generation scripts
>> - Updated the messenger doc snapshot
>> - Added messenger and protocol engine API doc in C, python, and java
>> - Added messenger examples in many languages
>> - Added make target and instructions for publishing content
>> - Improved the developer center
>> - Added 0.22 release content
>> - Overhauled the scripts for generating release content
>> - Added jms examples
>>
>> To better show the proposed launch state, I've made 0.22 the current
>> release in the preview site. As a result, some of the links won't
>> work because they point to things (such as a release tag) that don't
>> exist yet.
>>
>> I'd like to hold a vote in about a week on replacing our current
>> website. I'll have time for another update in the meantime, so please
>> let me know about any changes you'd like to see. In particular, take
>> a pass through the component page for the parts of Qpid you are
>> familiar with. I'd love to get some detailed corrections and
>> refinements.
>
> I think it is great!
I forgot to mention in my previous reply - I think the website is great also.
Big improvement. Well done Justin!
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by "Weston M. Price" <wp...@redhat.com>.
On May 22, 2013, at 11:35 AM, Justin Ross <jr...@apache.org> wrote:
> I ended up with "Qpid JCA - A JCA resource adapter for AMQP brokers",
> which is not quite what Gordon recommended. I added the AMQP
> qualification on the notion that we probably aren't perfectly generic
> with respect to jms impls. Please correct me!
Makes sense actually in that we are not generic with regards to JMS as we are AMQP specific. The only generic JMS adapter I know of is the one from the Glassfish project.
-W
>
> On Tue, May 14, 2013 at 11:29 AM, Weston M. Price <wp...@redhat.com> wrote:
>>
>> On May 14, 2013, at 4:45 AM, Gordon Sim <gs...@redhat.com> wrote:
>>
>>> On 05/10/2013 05:39 PM, Justin Ross wrote:
>>>> Update:
>>>> http://people.apache.org/~jross/transom/2013-05-10/
>>>> Previous versions:
>>>> http://people.apache.org/~jross/transom/2013-04-16/
>>>> http://people.apache.org/~jross/transom/2013-04-03/
>>>> http://people.apache.org/~jross/transom/2013-03-26/
>>>> http://people.apache.org/~jross/transom/2013-03-13/
>>>> Head version, for following things as they change:
>>>> http://people.apache.org/~jross/transom/head/
>>>> The source code and README:
>>>> https://github.com/ssorj/transom
>>>>
>>>> Some bigger changes:
>>>>
>>>> - Added scripts to generate release notes
>>>> - Added link to EAP 6 instructions in JCA page
>>>> - Added QMF api doc
>>>> - Add pdfs to book-generation scripts
>>>> - Updated the messenger doc snapshot
>>>> - Added messenger and protocol engine API doc in C, python, and java
>>>> - Added messenger examples in many languages
>>>> - Added make target and instructions for publishing content
>>>> - Improved the developer center
>>>> - Added 0.22 release content
>>>> - Overhauled the scripts for generating release content
>>>> - Added jms examples
>>>>
>>>> To better show the proposed launch state, I've made 0.22 the current
>>>> release in the preview site. As a result, some of the links won't
>>>> work because they point to things (such as a release tag) that don't
>>>> exist yet.
>>>>
>>>> I'd like to hold a vote in about a week on replacing our current
>>>> website. I'll have time for another update in the meantime, so please
>>>> let me know about any changes you'd like to see. In particular, take
>>>> a pass through the component page for the parts of Qpid you are
>>>> familiar with. I'd love to get some detailed corrections and
>>>> refinements.
>>>
>>> I think it is great!
>>>
>>> The one change regarding components I would suggest is for the JCA adapter. It states 'Qpid JCA - A JCA resource adapter for Qpid brokers' which is not really correct... there is nothing intrinsically that ties the JCA adapter to Qpid brokers. The adapter is really adapting the JMS client to a JEE application server environment. There may of course be current limitations around the protocols that it can use (which may effectively limit the brokers you can use it with).
>>>
>>
>>> As far as the home page goes, I think the JCA component would fit better in the 'build (rather than 'deploy') section. I see it as providing an API to AMQP from within a JEE environment.
>>>
>> Well said. I tend to agree in that AMQP is the underlying protocol/API and should probably be emphasized over being Qpid specific.
>>
>>> Being picky, the overview page could maybe benefit from a mention of JMS ("Each vendor had its own messaging API and its own wire protocol", "AMQP is the first open standard for messaging").
>>>
>>> But this is a big improvement and I would wholeheartedly vote to adopt it as soon as possible.
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
>>> For additional commands, e-mail: users-help@qpid.apache.org
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
>> For additional commands, e-mail: users-help@qpid.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by Justin Ross <jr...@apache.org>.
I ended up with "Qpid JCA - A JCA resource adapter for AMQP brokers",
which is not quite what Gordon recommended. I added the AMQP
qualification on the notion that we probably aren't perfectly generic
with respect to jms impls. Please correct me!
On Tue, May 14, 2013 at 11:29 AM, Weston M. Price <wp...@redhat.com> wrote:
>
> On May 14, 2013, at 4:45 AM, Gordon Sim <gs...@redhat.com> wrote:
>
>> On 05/10/2013 05:39 PM, Justin Ross wrote:
>>> Update:
>>> http://people.apache.org/~jross/transom/2013-05-10/
>>> Previous versions:
>>> http://people.apache.org/~jross/transom/2013-04-16/
>>> http://people.apache.org/~jross/transom/2013-04-03/
>>> http://people.apache.org/~jross/transom/2013-03-26/
>>> http://people.apache.org/~jross/transom/2013-03-13/
>>> Head version, for following things as they change:
>>> http://people.apache.org/~jross/transom/head/
>>> The source code and README:
>>> https://github.com/ssorj/transom
>>>
>>> Some bigger changes:
>>>
>>> - Added scripts to generate release notes
>>> - Added link to EAP 6 instructions in JCA page
>>> - Added QMF api doc
>>> - Add pdfs to book-generation scripts
>>> - Updated the messenger doc snapshot
>>> - Added messenger and protocol engine API doc in C, python, and java
>>> - Added messenger examples in many languages
>>> - Added make target and instructions for publishing content
>>> - Improved the developer center
>>> - Added 0.22 release content
>>> - Overhauled the scripts for generating release content
>>> - Added jms examples
>>>
>>> To better show the proposed launch state, I've made 0.22 the current
>>> release in the preview site. As a result, some of the links won't
>>> work because they point to things (such as a release tag) that don't
>>> exist yet.
>>>
>>> I'd like to hold a vote in about a week on replacing our current
>>> website. I'll have time for another update in the meantime, so please
>>> let me know about any changes you'd like to see. In particular, take
>>> a pass through the component page for the parts of Qpid you are
>>> familiar with. I'd love to get some detailed corrections and
>>> refinements.
>>
>> I think it is great!
>>
>> The one change regarding components I would suggest is for the JCA adapter. It states 'Qpid JCA - A JCA resource adapter for Qpid brokers' which is not really correct... there is nothing intrinsically that ties the JCA adapter to Qpid brokers. The adapter is really adapting the JMS client to a JEE application server environment. There may of course be current limitations around the protocols that it can use (which may effectively limit the brokers you can use it with).
>>
>
>> As far as the home page goes, I think the JCA component would fit better in the 'build (rather than 'deploy') section. I see it as providing an API to AMQP from within a JEE environment.
>>
> Well said. I tend to agree in that AMQP is the underlying protocol/API and should probably be emphasized over being Qpid specific.
>
>> Being picky, the overview page could maybe benefit from a mention of JMS ("Each vendor had its own messaging API and its own wire protocol", "AMQP is the first open standard for messaging").
>>
>> But this is a big improvement and I would wholeheartedly vote to adopt it as soon as possible.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
>> For additional commands, e-mail: users-help@qpid.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by "Weston M. Price" <wp...@redhat.com>.
On May 14, 2013, at 4:45 AM, Gordon Sim <gs...@redhat.com> wrote:
> On 05/10/2013 05:39 PM, Justin Ross wrote:
>> Update:
>> http://people.apache.org/~jross/transom/2013-05-10/
>> Previous versions:
>> http://people.apache.org/~jross/transom/2013-04-16/
>> http://people.apache.org/~jross/transom/2013-04-03/
>> http://people.apache.org/~jross/transom/2013-03-26/
>> http://people.apache.org/~jross/transom/2013-03-13/
>> Head version, for following things as they change:
>> http://people.apache.org/~jross/transom/head/
>> The source code and README:
>> https://github.com/ssorj/transom
>>
>> Some bigger changes:
>>
>> - Added scripts to generate release notes
>> - Added link to EAP 6 instructions in JCA page
>> - Added QMF api doc
>> - Add pdfs to book-generation scripts
>> - Updated the messenger doc snapshot
>> - Added messenger and protocol engine API doc in C, python, and java
>> - Added messenger examples in many languages
>> - Added make target and instructions for publishing content
>> - Improved the developer center
>> - Added 0.22 release content
>> - Overhauled the scripts for generating release content
>> - Added jms examples
>>
>> To better show the proposed launch state, I've made 0.22 the current
>> release in the preview site. As a result, some of the links won't
>> work because they point to things (such as a release tag) that don't
>> exist yet.
>>
>> I'd like to hold a vote in about a week on replacing our current
>> website. I'll have time for another update in the meantime, so please
>> let me know about any changes you'd like to see. In particular, take
>> a pass through the component page for the parts of Qpid you are
>> familiar with. I'd love to get some detailed corrections and
>> refinements.
>
> I think it is great!
>
> The one change regarding components I would suggest is for the JCA adapter. It states 'Qpid JCA - A JCA resource adapter for Qpid brokers' which is not really correct... there is nothing intrinsically that ties the JCA adapter to Qpid brokers. The adapter is really adapting the JMS client to a JEE application server environment. There may of course be current limitations around the protocols that it can use (which may effectively limit the brokers you can use it with).
>
> As far as the home page goes, I think the JCA component would fit better in the 'build (rather than 'deploy') section. I see it as providing an API to AMQP from within a JEE environment.
>
Well said. I tend to agree in that AMQP is the underlying protocol/API and should probably be emphasized over being Qpid specific.
> Being picky, the overview page could maybe benefit from a mention of JMS ("Each vendor had its own messaging API and its own wire protocol", "AMQP is the first open standard for messaging").
>
> But this is a big improvement and I would wholeheartedly vote to adopt it as soon as possible.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by Gordon Sim <gs...@redhat.com>.
On 05/10/2013 05:39 PM, Justin Ross wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't
> work because they point to things (such as a release tag) that don't
> exist yet.
>
> I'd like to hold a vote in about a week on replacing our current
> website. I'll have time for another update in the meantime, so please
> let me know about any changes you'd like to see. In particular, take
> a pass through the component page for the parts of Qpid you are
> familiar with. I'd love to get some detailed corrections and
> refinements.
I think it is great!
The one change regarding components I would suggest is for the JCA
adapter. It states 'Qpid JCA - A JCA resource adapter for Qpid brokers'
which is not really correct... there is nothing intrinsically that ties
the JCA adapter to Qpid brokers. The adapter is really adapting the JMS
client to a JEE application server environment. There may of course be
current limitations around the protocols that it can use (which may
effectively limit the brokers you can use it with).
As far as the home page goes, I think the JCA component would fit better
in the 'build (rather than 'deploy') section. I see it as providing an
API to AMQP from within a JEE environment.
Being picky, the overview page could maybe benefit from a mention of JMS
("Each vendor had its own messaging API and its own wire protocol",
"AMQP is the first open standard for messaging").
But this is a big improvement and I would wholeheartedly vote to adopt
it as soon as possible.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
On 25 May 2013 14:22, Justin Ross <ju...@gmail.com> wrote:
> I've mocked up nightly release pages in a way I hope is similar to how
> you envisioned it. I like how it turns out.
>
>
> http://people.apache.org/~jross/transom/head/releases/index.html#nightly-releases
>
> http://people.apache.org/~jross/transom/head/releases/qpid-nightly/index.html
>
> http://people.apache.org/~jross/transom/head/releases/qpid-proton-nightly/index.html
>
>
This is exactly what I was thinking, so I also like it :)
On the first link the setence about older releases seems like it should
move up a section, it was presumably in 'Past Releases' before?
> Most of the links on the release pages themselves are broken, and we
> need some more advisory text, but it serves to illustrate one way to
> do it.
>
> Things we'll need or want in order to fill in the broken links:
>
> - A place to push nightly builds.
> "http://www.apache.org/dist/qpid/nightly/" perhaps?
>
You aren't allowed to use the main dist area (and thus mirrors) for stuff
like this, only actual releases. There is now a separate dev distribution
area but I believe thats still only intended for e.g betas and release
candidates.
>
> - To adapt doc gen scripts to produce docs from trunk. I can
> definitely do that.
>
> - A way for a cron job to commit to our svnpubsub path. I'm not
> sure about this one.
>
I was envisaging that we would set up jobs on the Buildbot instances and
simply link to the job output, or if possible have those jobs able to
commit somewhere (with their own credentials) that uses svnpubsub to deploy
the output to a specific tree of the website that we wouldnt otherwise
touch ourselves.
>
> Justin
>
> On Fri, May 24, 2013 at 11:31 AM, Justin Ross <ju...@gmail.com>
> wrote:
> > On Fri, May 24, 2013 at 11:05 AM, Robbie Gemmell
> > <ro...@gmail.com> wrote:
> >> Part of me think that if we had a page that looked a bit bare then
> maybe we
> >> would be better about putting more stuff on it when people see it and
> >> wonder where the missing bits are. Hiding it away where people won't
> see it
> >> gives less incentive and also means that the stuff that already is there
> >> won't get used to the extent it could.
> >
> > Okay, I'll split it out.
> >
> >>> It would be my preference to treat trunk documentation as just another
> >>> kind of nightly build, with a prominent section next to other nightly
> >>> artifacts and a link from the documentation page.
> >>>
> >>
> >> I was thinking along the lines of 'nightly release' page(s)...such that
> by
> >> the time it comes to the point to release the component(s) it should to
> >> some extent effectively be a case of making a copy of what has already
> been
> >> published previously for the component(s).
> >
> > Okay, that seems like a fine approach. For what it's worth, it's a
> > little annoying from the scripting standpoint because you need to
> > conditionally link to trunk or a branch, and you need to
> > conditionalize other stuff as well, such as download links. Right now
> > the scripts count on there being tags in svn and artifacts up on dist.
> >
> > But that's not the big piece of work. To really make a "nightly
> > release" look just like a numbered release, we have a fair bit of work
> > to do yet to automate builds.
> >
> >> I might be the exception, but when I bother myself to write new docs I
> tend
> >> to want them on the site and publish them immediately.
> >
> > There's no blocking problem with doing this. The trunk docs can be
> > generated and pushed in a different fashion. There's no terribly
> > great need to add the site nav around the trunk docs, though I agree
> > it would be nice once the above mentioned scripting is sorted out.
> >
> > Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
I've mocked up nightly release pages in a way I hope is similar to how
you envisioned it. I like how it turns out.
http://people.apache.org/~jross/transom/head/releases/index.html#nightly-releases
http://people.apache.org/~jross/transom/head/releases/qpid-nightly/index.html
http://people.apache.org/~jross/transom/head/releases/qpid-proton-nightly/index.html
Most of the links on the release pages themselves are broken, and we
need some more advisory text, but it serves to illustrate one way to
do it.
Things we'll need or want in order to fill in the broken links:
- A place to push nightly builds.
"http://www.apache.org/dist/qpid/nightly/" perhaps?
- To adapt doc gen scripts to produce docs from trunk. I can
definitely do that.
- A way for a cron job to commit to our svnpubsub path. I'm not
sure about this one.
Justin
On Fri, May 24, 2013 at 11:31 AM, Justin Ross <ju...@gmail.com> wrote:
> On Fri, May 24, 2013 at 11:05 AM, Robbie Gemmell
> <ro...@gmail.com> wrote:
>> Part of me think that if we had a page that looked a bit bare then maybe we
>> would be better about putting more stuff on it when people see it and
>> wonder where the missing bits are. Hiding it away where people won't see it
>> gives less incentive and also means that the stuff that already is there
>> won't get used to the extent it could.
>
> Okay, I'll split it out.
>
>>> It would be my preference to treat trunk documentation as just another
>>> kind of nightly build, with a prominent section next to other nightly
>>> artifacts and a link from the documentation page.
>>>
>>
>> I was thinking along the lines of 'nightly release' page(s)...such that by
>> the time it comes to the point to release the component(s) it should to
>> some extent effectively be a case of making a copy of what has already been
>> published previously for the component(s).
>
> Okay, that seems like a fine approach. For what it's worth, it's a
> little annoying from the scripting standpoint because you need to
> conditionally link to trunk or a branch, and you need to
> conditionalize other stuff as well, such as download links. Right now
> the scripts count on there being tags in svn and artifacts up on dist.
>
> But that's not the big piece of work. To really make a "nightly
> release" look just like a numbered release, we have a fair bit of work
> to do yet to automate builds.
>
>> I might be the exception, but when I bother myself to write new docs I tend
>> to want them on the site and publish them immediately.
>
> There's no blocking problem with doing this. The trunk docs can be
> generated and pushed in a different fashion. There's no terribly
> great need to add the site nav around the trunk docs, though I agree
> it would be nice once the above mentioned scripting is sorted out.
>
> Justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
On Fri, May 24, 2013 at 11:05 AM, Robbie Gemmell
<ro...@gmail.com> wrote:
> Part of me think that if we had a page that looked a bit bare then maybe we
> would be better about putting more stuff on it when people see it and
> wonder where the missing bits are. Hiding it away where people won't see it
> gives less incentive and also means that the stuff that already is there
> won't get used to the extent it could.
Okay, I'll split it out.
>> It would be my preference to treat trunk documentation as just another
>> kind of nightly build, with a prominent section next to other nightly
>> artifacts and a link from the documentation page.
>>
>
> I was thinking along the lines of 'nightly release' page(s)...such that by
> the time it comes to the point to release the component(s) it should to
> some extent effectively be a case of making a copy of what has already been
> published previously for the component(s).
Okay, that seems like a fine approach. For what it's worth, it's a
little annoying from the scripting standpoint because you need to
conditionally link to trunk or a branch, and you need to
conditionalize other stuff as well, such as download links. Right now
the scripts count on there being tags in svn and artifacts up on dist.
But that's not the big piece of work. To really make a "nightly
release" look just like a numbered release, we have a fair bit of work
to do yet to automate builds.
> I might be the exception, but when I bother myself to write new docs I tend
> to want them on the site and publish them immediately.
There's no blocking problem with doing this. The trunk docs can be
generated and pushed in a different fashion. There's no terribly
great need to add the site nav around the trunk docs, though I agree
it would be nice once the above mentioned scripting is sorted out.
Justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
On 24 May 2013 12:30, Justin Ross <ju...@gmail.com> wrote:
> Some of the issues you raise will be addressed in an upcoming "update"
> mail, so I won't address them here.
>
> On Sun, May 19, 2013 at 9:00 PM, Robbie Gemmell
> <ro...@gmail.com> wrote:
> > I think it was Jakub who previously mentioned the lack of links to trunk
> > documentation. I too find their absence noticable as they are the only
> > documentation links I tend to use outside of testing the releases. 15
> > minutes after I wrote that, I just accidentally came across links to
> trunk
> > documentation for the Java broker and Programming (but not C++ broker)
> > books hidden away in More Resources, taking me on to the next point
> which I
> > wrote before this sentence existed.
>
> I like the idea of trunk documentation, but only if it's actually
> something kept up to date. I left the links to the Java broker and
> Programming books because I know you want them, but the others are
> currently more often stale than fresh.
>
> Once we do have nightly builds for the docs, I'm all in favor of this.
>
> > Linking the above points together it might also be nice to have a
> 'nightly
> > release' page. We generate nightly builds for the Java components and
> push
> > out the maven artifacts to the snapshots repo, doing the equivalent for
> all
> > the components would probably help improve the release process if we made
> > it easier for people to test things whenever they like rather than always
> > waiting for the next RC to drop before discovering things aren't as
> > expected.
>
> For now, I've left this as a small section under "More Resources".
> That's simply because at this point we don't have enough content there
> for it to merit its own page.
>
Part of me think that if we had a page that looked a bit bare then maybe we
would be better about putting more stuff on it when people see it and
wonder where the missing bits are. Hiding it away where people won't see it
gives less incentive and also means that the stuff that already is there
won't get used to the extent it could.
>
> Send me the specifics for the snapshot repo, and I'll work them in.
>
https://repository.apache.org/content/repositories/snapshots/
>
> It would be my preference to treat trunk documentation as just another
> kind of nightly build, with a prominent section next to other nightly
> artifacts and a link from the documentation page.
>
I was thinking along the lines of 'nightly release' page(s)...such that by
the time it comes to the point to release the component(s) it should to
some extent effectively be a case of making a copy of what has already been
published previously for the component(s).
>
> > I noticed several links out to the wiki, e.g:
> > From the developers page:
> > https://cwiki.apache.org/qpid/qpid-project-etiquette-guide.html
> > From the source code page:
> > https://cwiki.apache.org/qpid/getting-started-guide.html
> > From the Java Broker component page 'features':
> > https://cwiki.apache.org/qpid/configure-operational-status-logging.html
> >
> https://cwiki.apache.org/qpid/configure-broker-and-client-heartbeating.html
> >
> https://cwiki.apache.org/qpid/configure-the-virtual-hosts-via-virtualhostsxml.html
> > From the Java Broker component page 'documentation' :
> > https://cwiki.apache.org/qpid/qpid-java-build-how-to.html
> > https://cwiki.apache.org/qpid/getting-started-guide.html
> > https://cwiki.apache.org/qpid/qpid-java-faq.html
> > https://cwiki.apache.org/qpid/qpid-troubleshooting-guide.html
> > https://cwiki.apache.org/qpid/java-broker-design.html
> > https://cwiki.apache.org/qpid/qpid-java-documentation.html
> >
> > The content from some of these has been on the main website for years,
> > others are now part of the source controlled documentation, and most of
> > them are partially or entirely out of date. I think we should avoid
> linking
> > out to the wiki where possible, particularly for end user documentation.
> It
> > disrupts the flow of using the site, looks pretty poor in comparison, is
> > often kind of slow, and is mostly out of date at this point. We have been
> > and should continue to look to get as much of the actual user
> documentation
> > we consider current into the source-controlled documentation we keep to
> > help ensure it is kept relevant to the specific releases, rather than
> > collect lots of cruft that will go stale the way the old wiki based site
> > clearly has over the years. I would like to see us finish transitioning
> any
> > remaining useful user documentation that remains only on the wiki over to
> > the website or source controlled docs and then pretty much entirely nuke
> > the wiki from orbit and proceed with only the things it makes sense to
> keep
> > there. Then if we are linking out to wiki content I would probably link
> to
> > the actual wiki itself and not the transformed HTML copy of it (which we
> > should probably get deleted some day to clear out old stale pages since
> it
> > doesn't seem to remove things when you delete wiki pages).
>
> This is interesting. I have been operating from the other side of
> this, thinking the next thing I would turn to is cleaning up the
> content of the wiki and making it more presentable. I like the wiki
> for developer documents well enough, and I don't mind being the one
> who "owns" the problem of keeping the wiki in shape.
>
I dont have a particular problem with the wiki being used for e.g certain
developer docs (some of the ones above I'd say should be on the website, or
indeed already were) and general 'things that a wiki is suited to' like
working up a proposal for Feature X etc.
I'd just prefer that if we do so it is remotely up to date, and the
majority of the information currently on it is rather massively out of
date. I think much of it is beyond recovery, say 3-5 years in some cases,
and its time to simply delete it. I'll add that to my list of 'things to do
when bored'.
> For user documentation, I agree. Indeed, most of the user doc is tied
> to a release and belongs under source control. In general, I've tried
> to link out to the wiki (or jira) for user documentation only when I
> couldn't find the equivalent information in the formal docs. Any
> corrections would be very much appreciated, now, or in the future when
> content is migrated.
>
I'll have a look through at the weekend and come up with concrete
suggestions...off hand, half the things I linked above would currently be
on my 'to delete' list and so I'd be looking not to link to them.
>
> > I had a quick look at the source and had a couple of questions:
> >
> > Am I right in thinking you now need to perform 2 generation steps to get
> > from the docbook source to having output that can be put up on the site?
> > This seems a little cumbersome, especially given the current single
> > generation step seems to make people too lazy to publish their changes on
> > the site as it is (though I guess we should just get around to automating
> > this with a build on the ASF Buildbot instances and link to that).
>
> Sort of. In general, for release content, there's a special
> generation step. That's really a per-release task, however, not
> something that many developers would typically do.
I might be the exception, but when I bother myself to write new docs I tend
to want them on the site and publish them immediately.
> The idea is that
> the release manager would do the generation with each new release.
>
Sort of related to the earlier point on nightlies, I think we should be
preparing the release content as we go so that the release itself is as
close to a no-op as possible for the release manager.
> I've spent a good deal of time to make this easy (much easier than
> it's been in the past), probably because it's one of the jobs I've had
> to do with each release.
>
> Also, I guess I should say that the two steps are easily collapsed:
> "make gen-release RELEASE=0.22 render".
>
> Trunk documentation would, as you suggest, best be solved by automated
> builds.
>
> > I noticed some html files that just look to be doing redirects with meta
> > refresh. Would it not be better to use an .htaccess file and have the web
> > server do the redirect? (Or in the case of the documentation page that I
> > originally noticed it in, just actually have a documentation page as
> > mentioned)
>
> I looked at this, and I (a) don't think the meta redirects are very
> bad and (b) don't feel super great about rewrite use in .htaccess
> (see http://httpd.apache.org/docs/current/howto/htaccess.html#when).
> That said, I don't really care about it very strongly.
>
The .htaccess support is already enabled, so any necessary overhead is
already being incurred. We are using .htaccess redirects currently, it is
basically just how such user configuration tends to be permitted on shared
webservers.
I could be wrong but I have long been under the impression that use of
meta-refresh was discouraged in favour of server side redirection.
> > Finally, in the instructions for publishing people also need to check if
> > any pages have been removed/renamed, as just copying the new stuff over
> the
> > top wont show that and the old output will then be left to go stale (much
> > as with the transformed wiki html output).
>
> Yes, good point. I'll work on a script to check for stale files.
>
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
On 24 May 2013 12:30, Justin Ross <ju...@gmail.com> wrote:
> Some of the issues you raise will be addressed in an upcoming "update"
> mail, so I won't address them here.
>
> On Sun, May 19, 2013 at 9:00 PM, Robbie Gemmell
> <ro...@gmail.com> wrote:
> > I think it was Jakub who previously mentioned the lack of links to trunk
> > documentation. I too find their absence noticable as they are the only
> > documentation links I tend to use outside of testing the releases. 15
> > minutes after I wrote that, I just accidentally came across links to
> trunk
> > documentation for the Java broker and Programming (but not C++ broker)
> > books hidden away in More Resources, taking me on to the next point
> which I
> > wrote before this sentence existed.
>
> I like the idea of trunk documentation, but only if it's actually
> something kept up to date. I left the links to the Java broker and
> Programming books because I know you want them, but the others are
> currently more often stale than fresh.
>
> Once we do have nightly builds for the docs, I'm all in favor of this.
>
> > Linking the above points together it might also be nice to have a
> 'nightly
> > release' page. We generate nightly builds for the Java components and
> push
> > out the maven artifacts to the snapshots repo, doing the equivalent for
> all
> > the components would probably help improve the release process if we made
> > it easier for people to test things whenever they like rather than always
> > waiting for the next RC to drop before discovering things aren't as
> > expected.
>
> For now, I've left this as a small section under "More Resources".
> That's simply because at this point we don't have enough content there
> for it to merit its own page.
>
Part of me think that if we had a page that looked a bit bare then maybe we
would be better about putting more stuff on it when people see it and
wonder where the missing bits are. Hiding it away where people won't see it
gives less incentive and also means that the stuff that already is there
won't get used to the extent it could.
>
> Send me the specifics for the snapshot repo, and I'll work them in.
>
https://repository.apache.org/content/repositories/snapshots/
>
> It would be my preference to treat trunk documentation as just another
> kind of nightly build, with a prominent section next to other nightly
> artifacts and a link from the documentation page.
>
I was thinking along the lines of 'nightly release' page(s)...such that by
the time it comes to the point to release the component(s) it should to
some extent effectively be a case of making a copy of what has already been
published previously for the component(s).
>
> > I noticed several links out to the wiki, e.g:
> > From the developers page:
> > https://cwiki.apache.org/qpid/qpid-project-etiquette-guide.html
> > From the source code page:
> > https://cwiki.apache.org/qpid/getting-started-guide.html
> > From the Java Broker component page 'features':
> > https://cwiki.apache.org/qpid/configure-operational-status-logging.html
> >
> https://cwiki.apache.org/qpid/configure-broker-and-client-heartbeating.html
> >
> https://cwiki.apache.org/qpid/configure-the-virtual-hosts-via-virtualhostsxml.html
> > From the Java Broker component page 'documentation' :
> > https://cwiki.apache.org/qpid/qpid-java-build-how-to.html
> > https://cwiki.apache.org/qpid/getting-started-guide.html
> > https://cwiki.apache.org/qpid/qpid-java-faq.html
> > https://cwiki.apache.org/qpid/qpid-troubleshooting-guide.html
> > https://cwiki.apache.org/qpid/java-broker-design.html
> > https://cwiki.apache.org/qpid/qpid-java-documentation.html
> >
> > The content from some of these has been on the main website for years,
> > others are now part of the source controlled documentation, and most of
> > them are partially or entirely out of date. I think we should avoid
> linking
> > out to the wiki where possible, particularly for end user documentation.
> It
> > disrupts the flow of using the site, looks pretty poor in comparison, is
> > often kind of slow, and is mostly out of date at this point. We have been
> > and should continue to look to get as much of the actual user
> documentation
> > we consider current into the source-controlled documentation we keep to
> > help ensure it is kept relevant to the specific releases, rather than
> > collect lots of cruft that will go stale the way the old wiki based site
> > clearly has over the years. I would like to see us finish transitioning
> any
> > remaining useful user documentation that remains only on the wiki over to
> > the website or source controlled docs and then pretty much entirely nuke
> > the wiki from orbit and proceed with only the things it makes sense to
> keep
> > there. Then if we are linking out to wiki content I would probably link
> to
> > the actual wiki itself and not the transformed HTML copy of it (which we
> > should probably get deleted some day to clear out old stale pages since
> it
> > doesn't seem to remove things when you delete wiki pages).
>
> This is interesting. I have been operating from the other side of
> this, thinking the next thing I would turn to is cleaning up the
> content of the wiki and making it more presentable. I like the wiki
> for developer documents well enough, and I don't mind being the one
> who "owns" the problem of keeping the wiki in shape.
>
I dont have a particular problem with the wiki being used for e.g certain
developer docs (some of the ones above I'd say should be on the website, or
indeed already were) and general 'things that a wiki is suited to' like
working up a proposal for Feature X etc.
I'd just prefer that if we do so it is remotely up to date, and the
majority of the information currently on it is rather massively out of
date. I think much of it is beyond recovery, say 3-5 years in some cases,
and its time to simply delete it. I'll add that to my list of 'things to do
when bored'.
> For user documentation, I agree. Indeed, most of the user doc is tied
> to a release and belongs under source control. In general, I've tried
> to link out to the wiki (or jira) for user documentation only when I
> couldn't find the equivalent information in the formal docs. Any
> corrections would be very much appreciated, now, or in the future when
> content is migrated.
>
I'll have a look through at the weekend and come up with concrete
suggestions...off hand, half the things I linked above would currently be
on my 'to delete' list and so I'd be looking not to link to them.
>
> > I had a quick look at the source and had a couple of questions:
> >
> > Am I right in thinking you now need to perform 2 generation steps to get
> > from the docbook source to having output that can be put up on the site?
> > This seems a little cumbersome, especially given the current single
> > generation step seems to make people too lazy to publish their changes on
> > the site as it is (though I guess we should just get around to automating
> > this with a build on the ASF Buildbot instances and link to that).
>
> Sort of. In general, for release content, there's a special
> generation step. That's really a per-release task, however, not
> something that many developers would typically do.
I might be the exception, but when I bother myself to write new docs I tend
to want them on the site and publish them immediately.
> The idea is that
> the release manager would do the generation with each new release.
>
Sort of related to the earlier point on nightlies, I think we should be
preparing the release content as we go so that the release itself is as
close to a no-op as possible for the release manager.
> I've spent a good deal of time to make this easy (much easier than
> it's been in the past), probably because it's one of the jobs I've had
> to do with each release.
>
> Also, I guess I should say that the two steps are easily collapsed:
> "make gen-release RELEASE=0.22 render".
>
> Trunk documentation would, as you suggest, best be solved by automated
> builds.
>
> > I noticed some html files that just look to be doing redirects with meta
> > refresh. Would it not be better to use an .htaccess file and have the web
> > server do the redirect? (Or in the case of the documentation page that I
> > originally noticed it in, just actually have a documentation page as
> > mentioned)
>
> I looked at this, and I (a) don't think the meta redirects are very
> bad and (b) don't feel super great about rewrite use in .htaccess
> (see http://httpd.apache.org/docs/current/howto/htaccess.html#when).
> That said, I don't really care about it very strongly.
>
The .htaccess support is already enabled, so any necessary overhead is
already being incurred. We are using .htaccess redirects currently, it is
basically just how such user configuration tends to be permitted on shared
webservers.
I could be wrong but I have long been under the impression that use of
meta-refresh was discouraged in favour of server side redirection.
> > Finally, in the instructions for publishing people also need to check if
> > any pages have been removed/renamed, as just copying the new stuff over
> the
> > top wont show that and the old output will then be left to go stale (much
> > as with the transformed wiki html output).
>
> Yes, good point. I'll work on a script to check for stale files.
>
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
That's something I have looked at a little. I intend to do a deeper
investigation after 0.22 and the big site update.
On Fri, May 24, 2013 at 9:28 AM, Rajith Attapattu <ra...@gmail.com> wrote:
> On Fri, May 24, 2013 at 8:56 AM, Justin Ross <ju...@gmail.com> wrote:
>
>> On Fri, May 24, 2013 at 8:37 AM, Rob Godfrey >> Sort of. In general,
>> for release content, there's a special
>> >> generation step. That's really a per-release task, however, not
>> >> something that many developers would typically do. The idea is that
>> >> the release manager would do the generation with each new release.
>> >> I've spent a good deal of time to make this easy (much easier than
>> >> it's been in the past), probably because it's one of the jobs I've had
>> >> to do with each release.
>> >>
>> >> Also, I guess I should say that the two steps are easily collapsed:
>> >> "make gen-release RELEASE=0.22 render".
>> >>
>> >> Trunk documentation would, as you suggest, best be solved by automated
>> >> builds.
>> >>
>> >>
>> > So I'm at a bit of a loss as to why a two step document generation
>> process
>> > would be a good idea. Is there something that is now being done that
>> > cannot be done using the docbook -> html XSL transforms? I'm not the
>> > greatest fan of docbook, but adding in a secondary transform on top of an
>> > existing transform seems a little odd. If docbook cannot give us the
>> > output we need, why are we still using docbook?
>>
>> Agreed about docbook; I'm not a fan, and I'd love to move away from it.
>>
>
> Markdown is a more friendly (and less clunky format) and the doc is
> readable on it's own.
> There ware ways to convert docbook to Markdown. So maybe we should look at
> that option.
>
> What do u think ?
>
>
>>
>> It's more like an import step. The docbook content is (sensibly)
>> maintained under the main qpid source tree. The web content is
>> (sensibly) maintained under the website source. On the website, we
>> fuse the two together for the release docs, mating the website
>> template (with its navigation) to the body html from docbook. Indeed,
>> I favor removing the site template stuff from the docbook scripts
>> under the qpid source tree. I currently scrub it out.
>>
>> There's another less important reason. Docbook generates lousy html,
>> so I sanitize it (to xhtml) to make things like link checking work
>> nicely.
>>
>> Justin
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
>> For additional commands, e-mail: dev-help@qpid.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Rajith Attapattu <ra...@gmail.com>.
On Fri, May 24, 2013 at 8:56 AM, Justin Ross <ju...@gmail.com> wrote:
> On Fri, May 24, 2013 at 8:37 AM, Rob Godfrey >> Sort of. In general,
> for release content, there's a special
> >> generation step. That's really a per-release task, however, not
> >> something that many developers would typically do. The idea is that
> >> the release manager would do the generation with each new release.
> >> I've spent a good deal of time to make this easy (much easier than
> >> it's been in the past), probably because it's one of the jobs I've had
> >> to do with each release.
> >>
> >> Also, I guess I should say that the two steps are easily collapsed:
> >> "make gen-release RELEASE=0.22 render".
> >>
> >> Trunk documentation would, as you suggest, best be solved by automated
> >> builds.
> >>
> >>
> > So I'm at a bit of a loss as to why a two step document generation
> process
> > would be a good idea. Is there something that is now being done that
> > cannot be done using the docbook -> html XSL transforms? I'm not the
> > greatest fan of docbook, but adding in a secondary transform on top of an
> > existing transform seems a little odd. If docbook cannot give us the
> > output we need, why are we still using docbook?
>
> Agreed about docbook; I'm not a fan, and I'd love to move away from it.
>
Markdown is a more friendly (and less clunky format) and the doc is
readable on it's own.
There ware ways to convert docbook to Markdown. So maybe we should look at
that option.
What do u think ?
>
> It's more like an import step. The docbook content is (sensibly)
> maintained under the main qpid source tree. The web content is
> (sensibly) maintained under the website source. On the website, we
> fuse the two together for the release docs, mating the website
> template (with its navigation) to the body html from docbook. Indeed,
> I favor removing the site template stuff from the docbook scripts
> under the qpid source tree. I currently scrub it out.
>
> There's another less important reason. Docbook generates lousy html,
> so I sanitize it (to xhtml) to make things like link checking work
> nicely.
>
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
On Fri, May 24, 2013 at 8:37 AM, Rob Godfrey >> Sort of. In general,
for release content, there's a special
>> generation step. That's really a per-release task, however, not
>> something that many developers would typically do. The idea is that
>> the release manager would do the generation with each new release.
>> I've spent a good deal of time to make this easy (much easier than
>> it's been in the past), probably because it's one of the jobs I've had
>> to do with each release.
>>
>> Also, I guess I should say that the two steps are easily collapsed:
>> "make gen-release RELEASE=0.22 render".
>>
>> Trunk documentation would, as you suggest, best be solved by automated
>> builds.
>>
>>
> So I'm at a bit of a loss as to why a two step document generation process
> would be a good idea. Is there something that is now being done that
> cannot be done using the docbook -> html XSL transforms? I'm not the
> greatest fan of docbook, but adding in a secondary transform on top of an
> existing transform seems a little odd. If docbook cannot give us the
> output we need, why are we still using docbook?
Agreed about docbook; I'm not a fan, and I'd love to move away from it.
It's more like an import step. The docbook content is (sensibly)
maintained under the main qpid source tree. The web content is
(sensibly) maintained under the website source. On the website, we
fuse the two together for the release docs, mating the website
template (with its navigation) to the body html from docbook. Indeed,
I favor removing the site template stuff from the docbook scripts
under the qpid source tree. I currently scrub it out.
There's another less important reason. Docbook generates lousy html,
so I sanitize it (to xhtml) to make things like link checking work
nicely.
Justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Rob Godfrey <ro...@gmail.com>.
On 24 May 2013 13:30, Justin Ross <ju...@gmail.com> wrote:
> Some of the issues you raise will be addressed in an upcoming "update"
> mail, so I won't address them here.
>
> On Sun, May 19, 2013 at 9:00 PM, Robbie Gemmell
> <ro...@gmail.com> wrote:
>
[.. snip ..]
> > I had a quick look at the source and had a couple of questions:
> >
> > Am I right in thinking you now need to perform 2 generation steps to get
> > from the docbook source to having output that can be put up on the site?
> > This seems a little cumbersome, especially given the current single
> > generation step seems to make people too lazy to publish their changes on
> > the site as it is (though I guess we should just get around to automating
> > this with a build on the ASF Buildbot instances and link to that).
>
> Sort of. In general, for release content, there's a special
> generation step. That's really a per-release task, however, not
> something that many developers would typically do. The idea is that
> the release manager would do the generation with each new release.
> I've spent a good deal of time to make this easy (much easier than
> it's been in the past), probably because it's one of the jobs I've had
> to do with each release.
>
> Also, I guess I should say that the two steps are easily collapsed:
> "make gen-release RELEASE=0.22 render".
>
> Trunk documentation would, as you suggest, best be solved by automated
> builds.
>
>
So I'm at a bit of a loss as to why a two step document generation process
would be a good idea. Is there something that is now being done that
cannot be done using the docbook -> html XSL transforms? I'm not the
greatest fan of docbook, but adding in a secondary transform on top of an
existing transform seems a little odd. If docbook cannot give us the
output we need, why are we still using docbook?
-- Rob
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
Some of the issues you raise will be addressed in an upcoming "update"
mail, so I won't address them here.
On Sun, May 19, 2013 at 9:00 PM, Robbie Gemmell
<ro...@gmail.com> wrote:
> I think it was Jakub who previously mentioned the lack of links to trunk
> documentation. I too find their absence noticable as they are the only
> documentation links I tend to use outside of testing the releases. 15
> minutes after I wrote that, I just accidentally came across links to trunk
> documentation for the Java broker and Programming (but not C++ broker)
> books hidden away in More Resources, taking me on to the next point which I
> wrote before this sentence existed.
I like the idea of trunk documentation, but only if it's actually
something kept up to date. I left the links to the Java broker and
Programming books because I know you want them, but the others are
currently more often stale than fresh.
Once we do have nightly builds for the docs, I'm all in favor of this.
> Linking the above points together it might also be nice to have a 'nightly
> release' page. We generate nightly builds for the Java components and push
> out the maven artifacts to the snapshots repo, doing the equivalent for all
> the components would probably help improve the release process if we made
> it easier for people to test things whenever they like rather than always
> waiting for the next RC to drop before discovering things aren't as
> expected.
For now, I've left this as a small section under "More Resources".
That's simply because at this point we don't have enough content there
for it to merit its own page.
Send me the specifics for the snapshot repo, and I'll work them in.
It would be my preference to treat trunk documentation as just another
kind of nightly build, with a prominent section next to other nightly
artifacts and a link from the documentation page.
> I noticed several links out to the wiki, e.g:
> From the developers page:
> https://cwiki.apache.org/qpid/qpid-project-etiquette-guide.html
> From the source code page:
> https://cwiki.apache.org/qpid/getting-started-guide.html
> From the Java Broker component page 'features':
> https://cwiki.apache.org/qpid/configure-operational-status-logging.html
> https://cwiki.apache.org/qpid/configure-broker-and-client-heartbeating.html
> https://cwiki.apache.org/qpid/configure-the-virtual-hosts-via-virtualhostsxml.html
> From the Java Broker component page 'documentation' :
> https://cwiki.apache.org/qpid/qpid-java-build-how-to.html
> https://cwiki.apache.org/qpid/getting-started-guide.html
> https://cwiki.apache.org/qpid/qpid-java-faq.html
> https://cwiki.apache.org/qpid/qpid-troubleshooting-guide.html
> https://cwiki.apache.org/qpid/java-broker-design.html
> https://cwiki.apache.org/qpid/qpid-java-documentation.html
>
> The content from some of these has been on the main website for years,
> others are now part of the source controlled documentation, and most of
> them are partially or entirely out of date. I think we should avoid linking
> out to the wiki where possible, particularly for end user documentation. It
> disrupts the flow of using the site, looks pretty poor in comparison, is
> often kind of slow, and is mostly out of date at this point. We have been
> and should continue to look to get as much of the actual user documentation
> we consider current into the source-controlled documentation we keep to
> help ensure it is kept relevant to the specific releases, rather than
> collect lots of cruft that will go stale the way the old wiki based site
> clearly has over the years. I would like to see us finish transitioning any
> remaining useful user documentation that remains only on the wiki over to
> the website or source controlled docs and then pretty much entirely nuke
> the wiki from orbit and proceed with only the things it makes sense to keep
> there. Then if we are linking out to wiki content I would probably link to
> the actual wiki itself and not the transformed HTML copy of it (which we
> should probably get deleted some day to clear out old stale pages since it
> doesn't seem to remove things when you delete wiki pages).
This is interesting. I have been operating from the other side of
this, thinking the next thing I would turn to is cleaning up the
content of the wiki and making it more presentable. I like the wiki
for developer documents well enough, and I don't mind being the one
who "owns" the problem of keeping the wiki in shape.
For user documentation, I agree. Indeed, most of the user doc is tied
to a release and belongs under source control. In general, I've tried
to link out to the wiki (or jira) for user documentation only when I
couldn't find the equivalent information in the formal docs. Any
corrections would be very much appreciated, now, or in the future when
content is migrated.
> I had a quick look at the source and had a couple of questions:
>
> Am I right in thinking you now need to perform 2 generation steps to get
> from the docbook source to having output that can be put up on the site?
> This seems a little cumbersome, especially given the current single
> generation step seems to make people too lazy to publish their changes on
> the site as it is (though I guess we should just get around to automating
> this with a build on the ASF Buildbot instances and link to that).
Sort of. In general, for release content, there's a special
generation step. That's really a per-release task, however, not
something that many developers would typically do. The idea is that
the release manager would do the generation with each new release.
I've spent a good deal of time to make this easy (much easier than
it's been in the past), probably because it's one of the jobs I've had
to do with each release.
Also, I guess I should say that the two steps are easily collapsed:
"make gen-release RELEASE=0.22 render".
Trunk documentation would, as you suggest, best be solved by automated builds.
> I noticed some html files that just look to be doing redirects with meta
> refresh. Would it not be better to use an .htaccess file and have the web
> server do the redirect? (Or in the case of the documentation page that I
> originally noticed it in, just actually have a documentation page as
> mentioned)
I looked at this, and I (a) don't think the meta redirects are very
bad and (b) don't feel super great about rewrite use in .htaccess
(see http://httpd.apache.org/docs/current/howto/htaccess.html#when).
That said, I don't really care about it very strongly.
> Finally, in the instructions for publishing people also need to check if
> any pages have been removed/renamed, as just copying the new stuff over the
> top wont show that and the old output will then be left to go stale (much
> as with the transformed wiki html output).
Yes, good point. I'll work on a script to check for stale files.
Justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
Hi Justin,
I have been preparing this email bit by bit for several days, here it
finally is...sorry it's a bit long now :)
I took another look and the site continues to improve, good work!
I think it was Jakub who previously mentioned the lack of links to trunk
documentation. I too find their absence noticable as they are the only
documentation links I tend to use outside of testing the releases. 15
minutes after I wrote that, I just accidentally came across links to trunk
documentation for the Java broker and Programming (but not C++ broker)
books hidden away in More Resources, taking me on to the next point which I
wrote before this sentence existed.
I think we could do with retaining the Documentation page and link in the
menu. Each Release page does have links to all the documentation in that
release (so basically two sets currently: Proton, and everything except
Proton), but the individual release pages aren't themselves that obvious as
you only seem to get to them if you notice the bit of text on the download
page. Obviously each component page has links to its specific documentation
but it still feels a little harder to get to the docs than it seems it
should or already is on the existing site, so I think they need to be
linked to more prominently.
Linking the above points together it might also be nice to have a 'nightly
release' page. We generate nightly builds for the Java components and push
out the maven artifacts to the snapshots repo, doing the equivalent for all
the components would probably help improve the release process if we made
it easier for people to test things whenever they like rather than always
waiting for the next RC to drop before discovering things aren't as
expected.
I'm not a huge fan of the single-page HTML documentation and think we
should continue to offer the multi-page version, which is all we ever
offered in the past. Offering both seems like it would be reasonable, then
people can view which they prefer.
It has been mentioned before about the font seeming overly large. I'm not
sure if it was actually reduced already, but it remains larger than most if
not all other sites I typically read. Reading the documentation really made
it stick out, e.g. the table of contents are around two thirds longer than
on the existing site.
A couple of minor edits are needed on the download page:
The JCA download link says it is linking to the java broker package (though
it isn't actually).
The signature verification section has an odd version number: "pgpv
qpid-0.0.22.tar.gz.asc"
The contributers page could use a refresh, it doesn't have Fraser as a
committer.
It is probably time to have the logo discussion...yay.
I noticed several links out to the wiki, e.g:
>From the developers page:
https://cwiki.apache.org/qpid/qpid-project-etiquette-guide.html
>From the source code page:
https://cwiki.apache.org/qpid/getting-started-guide.html
>From the Java Broker component page 'features':
https://cwiki.apache.org/qpid/configure-operational-status-logging.html
https://cwiki.apache.org/qpid/configure-broker-and-client-heartbeating.html
https://cwiki.apache.org/qpid/configure-the-virtual-hosts-via-virtualhostsxml.html
>From the Java Broker component page 'documentation' :
https://cwiki.apache.org/qpid/qpid-java-build-how-to.html
https://cwiki.apache.org/qpid/getting-started-guide.html
https://cwiki.apache.org/qpid/qpid-java-faq.html
https://cwiki.apache.org/qpid/qpid-troubleshooting-guide.html
https://cwiki.apache.org/qpid/java-broker-design.html
https://cwiki.apache.org/qpid/qpid-java-documentation.html
The content from some of these has been on the main website for years,
others are now part of the source controlled documentation, and most of
them are partially or entirely out of date. I think we should avoid linking
out to the wiki where possible, particularly for end user documentation. It
disrupts the flow of using the site, looks pretty poor in comparison, is
often kind of slow, and is mostly out of date at this point. We have been
and should continue to look to get as much of the actual user documentation
we consider current into the source-controlled documentation we keep to
help ensure it is kept relevant to the specific releases, rather than
collect lots of cruft that will go stale the way the old wiki based site
clearly has over the years. I would like to see us finish transitioning any
remaining useful user documentation that remains only on the wiki over to
the website or source controlled docs and then pretty much entirely nuke
the wiki from orbit and proceed with only the things it makes sense to keep
there. Then if we are linking out to wiki content I would probably link to
the actual wiki itself and not the transformed HTML copy of it (which we
should probably get deleted some day to clear out old stale pages since it
doesn't seem to remove things when you delete wiki pages).
I had a quick look at the source and had a couple of questions:
Am I right in thinking you now need to perform 2 generation steps to get
from the docbook source to having output that can be put up on the site?
This seems a little cumbersome, especially given the current single
generation step seems to make people too lazy to publish their changes on
the site as it is (though I guess we should just get around to automating
this with a build on the ASF Buildbot instances and link to that).
I noticed some html files that just look to be doing redirects with meta
refresh. Would it not be better to use an .htaccess file and have the web
server do the redirect? (Or in the case of the documentation page that I
originally noticed it in, just actually have a documentation page as
mentioned)
Finally, in the instructions for publishing people also need to check if
any pages have been removed/renamed, as just copying the new stuff over the
top wont show that and the old output will then be left to go stale (much
as with the transformed wiki html output).
Robbie
On 10 May 2013 17:39, Justin Ross <jr...@apache.org> wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't
> work because they point to things (such as a release tag) that don't
> exist yet.
>
> I'd like to hold a vote in about a week on replacing our current
> website. I'll have time for another update in the meantime, so please
> let me know about any changes you'd like to see. In particular, take
> a pass through the component page for the parts of Qpid you are
> familiar with. I'd love to get some detailed corrections and
> refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Alan Conway <ac...@redhat.com>.
On 05/10/2013 12:39 PM, Justin Ross wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
Perhaps a Documentation link under Resources on the front page, leading to a
list of all the docs?
C++ Broker page: "High Availability" links to C++ broker book, suggest a link to
the HA chapter.
It's not immediately obvious what section you should read if you're just brought
to the book.
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't
> work because they point to things (such as a release tag) that don't
> exist yet.
>
> I'd like to hold a vote in about a week on replacing our current
> website. I'll have time for another update in the meantime, so please
> let me know about any changes you'd like to see. In particular, take
> a pass through the component page for the parts of Qpid you are
> familiar with. I'd love to get some detailed corrections and
> refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Website update 4
Posted by Alan Conway <ac...@redhat.com>.
On 05/10/2013 12:39 PM, Justin Ross wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
Perhaps a Documentation link under Resources on the front page, leading to a
list of all the docs?
C++ Broker page: "High Availability" links to C++ broker book, suggest a link to
the HA chapter.
It's not immediately obvious what section you should read if you're just brought
to the book.
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't
> work because they point to things (such as a release tag) that don't
> exist yet.
>
> I'd like to hold a vote in about a week on replacing our current
> website. I'll have time for another update in the meantime, so please
> let me know about any changes you'd like to see. In particular, take
> a pass through the component page for the parts of Qpid you are
> familiar with. I'd love to get some detailed corrections and
> refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
Having been the person progressing the last Great Logo Discussion, I knew
too well how they can proceed and I didn't wan't to see it get in the way
of the far more important discussion about the website content.
If we are getting ready to publish it though then I guess it is time to
have that discussion.
Robbie
On 10 May 2013 20:03, Justin Ross <ju...@gmail.com> wrote:
> <snip>
> Indeed, the logo is not a decided thing. I just stopped making any
> further changes after Robbie asked to consider it separately.
>
> Justin
>
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
Having been the person progressing the last Great Logo Discussion, I knew
too well how they can proceed and I didn't wan't to see it get in the way
of the far more important discussion about the website content.
If we are getting ready to publish it though then I guess it is time to
have that discussion.
Robbie
On 10 May 2013 20:03, Justin Ross <ju...@gmail.com> wrote:
> <snip>
> Indeed, the logo is not a decided thing. I just stopped making any
> further changes after Robbie asked to consider it separately.
>
> Justin
>
Re: Website update 4
Posted by Justin Ross <ju...@gmail.com>.
Hi, Steve. I'm very pleased that you like it.
Qpidcomponents.org has three problems:
- Fixes for the store code are no longer going to the rhmessaging repo
- Instead they're going to the "legacystore" module under
qpid/cpp; this is part of an ongoing effort by Kim van der Riet to
update the store interface
- Cumin and sesame no longer live there either; they're at fedoraproject.org
- I don't have access to it, so I can't fix it (I've asked and
received no response)
For these reasons, I'm not keen on linking to qpidcomponents.org.
What I obviously *should* do is link to the above named resources
somewhere in the site content.
Indeed, the logo is not a decided thing. I just stopped making any
further changes after Robbie asked to consider it separately.
Justin
On Fri, May 10, 2013 at 2:20 PM, Steve Huston <sh...@riverace.com> wrote:
> Looks very nice, Justin!
>
> I don't see a link or description of qpidcomponents.org - since that's where users can get the Linux store, I think that's important. Maybe off the Downloads page like now?
>
> Also, I am probably way out of date, but did I miss a discussion of changing the logo? I think it's cool, but don't remember discussing a change - it's probably me, but just asking.
>
> Thanks,
> -Steve
>
>> -----Original Message-----
>> From: Justin Ross [mailto:jross@apache.org]
>> Sent: Friday, May 10, 2013 12:39 PM
>> To: users@qpid.apache.org; dev@qpid.apache.org
>> Subject: Website update 4
>>
>> Update:
>> http://people.apache.org/~jross/transom/2013-05-10/
>> Previous versions:
>> http://people.apache.org/~jross/transom/2013-04-16/
>> http://people.apache.org/~jross/transom/2013-04-03/
>> http://people.apache.org/~jross/transom/2013-03-26/
>> http://people.apache.org/~jross/transom/2013-03-13/
>> Head version, for following things as they change:
>> http://people.apache.org/~jross/transom/head/
>> The source code and README:
>> https://github.com/ssorj/transom
>>
>> Some bigger changes:
>>
>> - Added scripts to generate release notes
>> - Added link to EAP 6 instructions in JCA page
>> - Added QMF api doc
>> - Add pdfs to book-generation scripts
>> - Updated the messenger doc snapshot
>> - Added messenger and protocol engine API doc in C, python, and java
>> - Added messenger examples in many languages
>> - Added make target and instructions for publishing content
>> - Improved the developer center
>> - Added 0.22 release content
>> - Overhauled the scripts for generating release content
>> - Added jms examples
>>
>> To better show the proposed launch state, I've made 0.22 the current
>> release in the preview site. As a result, some of the links won't work
>> because they point to things (such as a release tag) that don't exist yet.
>>
>> I'd like to hold a vote in about a week on replacing our current website. I'll
>> have time for another update in the meantime, so please let me know about
>> any changes you'd like to see. In particular, take a pass through the
>> component page for the parts of Qpid you are familiar with. I'd love to get
>> some detailed corrections and refinements.
>>
>> Thanks!
>> Justin
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org For additional
>> commands, e-mail: dev-help@qpid.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
RE: Website update 4
Posted by Andrew Stitcher <as...@redhat.com>.
On Fri, 2013-05-10 at 18:20 +0000, Steve Huston wrote:
> Looks very nice, Justin!
>
> I don't see a link or description of qpidcomponents.org - since that's where users can get the Linux store, I think that's important. Maybe off the Downloads page like now?
As of 0.22 The store is in the main qpid source base (in
qpid/cpp/src/qpid/legacystore). so we no longer have to point to
anywhere external to get it.
Andrew
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
RE: Website update 4
Posted by Steve Huston <sh...@riverace.com>.
Looks very nice, Justin!
I don't see a link or description of qpidcomponents.org - since that's where users can get the Linux store, I think that's important. Maybe off the Downloads page like now?
Also, I am probably way out of date, but did I miss a discussion of changing the logo? I think it's cool, but don't remember discussing a change - it's probably me, but just asking.
Thanks,
-Steve
> -----Original Message-----
> From: Justin Ross [mailto:jross@apache.org]
> Sent: Friday, May 10, 2013 12:39 PM
> To: users@qpid.apache.org; dev@qpid.apache.org
> Subject: Website update 4
>
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't work
> because they point to things (such as a release tag) that don't exist yet.
>
> I'd like to hold a vote in about a week on replacing our current website. I'll
> have time for another update in the meantime, so please let me know about
> any changes you'd like to see. In particular, take a pass through the
> component page for the parts of Qpid you are familiar with. I'd love to get
> some detailed corrections and refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org For additional
> commands, e-mail: dev-help@qpid.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: Website update 4
Posted by Robbie Gemmell <ro...@gmail.com>.
Hi Justin,
I have been preparing this email bit by bit for several days, here it
finally is...sorry it's a bit long now :)
I took another look and the site continues to improve, good work!
I think it was Jakub who previously mentioned the lack of links to trunk
documentation. I too find their absence noticable as they are the only
documentation links I tend to use outside of testing the releases. 15
minutes after I wrote that, I just accidentally came across links to trunk
documentation for the Java broker and Programming (but not C++ broker)
books hidden away in More Resources, taking me on to the next point which I
wrote before this sentence existed.
I think we could do with retaining the Documentation page and link in the
menu. Each Release page does have links to all the documentation in that
release (so basically two sets currently: Proton, and everything except
Proton), but the individual release pages aren't themselves that obvious as
you only seem to get to them if you notice the bit of text on the download
page. Obviously each component page has links to its specific documentation
but it still feels a little harder to get to the docs than it seems it
should or already is on the existing site, so I think they need to be
linked to more prominently.
Linking the above points together it might also be nice to have a 'nightly
release' page. We generate nightly builds for the Java components and push
out the maven artifacts to the snapshots repo, doing the equivalent for all
the components would probably help improve the release process if we made
it easier for people to test things whenever they like rather than always
waiting for the next RC to drop before discovering things aren't as
expected.
I'm not a huge fan of the single-page HTML documentation and think we
should continue to offer the multi-page version, which is all we ever
offered in the past. Offering both seems like it would be reasonable, then
people can view which they prefer.
It has been mentioned before about the font seeming overly large. I'm not
sure if it was actually reduced already, but it remains larger than most if
not all other sites I typically read. Reading the documentation really made
it stick out, e.g. the table of contents are around two thirds longer than
on the existing site.
A couple of minor edits are needed on the download page:
The JCA download link says it is linking to the java broker package (though
it isn't actually).
The signature verification section has an odd version number: "pgpv
qpid-0.0.22.tar.gz.asc"
The contributers page could use a refresh, it doesn't have Fraser as a
committer.
It is probably time to have the logo discussion...yay.
I noticed several links out to the wiki, e.g:
>From the developers page:
https://cwiki.apache.org/qpid/qpid-project-etiquette-guide.html
>From the source code page:
https://cwiki.apache.org/qpid/getting-started-guide.html
>From the Java Broker component page 'features':
https://cwiki.apache.org/qpid/configure-operational-status-logging.html
https://cwiki.apache.org/qpid/configure-broker-and-client-heartbeating.html
https://cwiki.apache.org/qpid/configure-the-virtual-hosts-via-virtualhostsxml.html
>From the Java Broker component page 'documentation' :
https://cwiki.apache.org/qpid/qpid-java-build-how-to.html
https://cwiki.apache.org/qpid/getting-started-guide.html
https://cwiki.apache.org/qpid/qpid-java-faq.html
https://cwiki.apache.org/qpid/qpid-troubleshooting-guide.html
https://cwiki.apache.org/qpid/java-broker-design.html
https://cwiki.apache.org/qpid/qpid-java-documentation.html
The content from some of these has been on the main website for years,
others are now part of the source controlled documentation, and most of
them are partially or entirely out of date. I think we should avoid linking
out to the wiki where possible, particularly for end user documentation. It
disrupts the flow of using the site, looks pretty poor in comparison, is
often kind of slow, and is mostly out of date at this point. We have been
and should continue to look to get as much of the actual user documentation
we consider current into the source-controlled documentation we keep to
help ensure it is kept relevant to the specific releases, rather than
collect lots of cruft that will go stale the way the old wiki based site
clearly has over the years. I would like to see us finish transitioning any
remaining useful user documentation that remains only on the wiki over to
the website or source controlled docs and then pretty much entirely nuke
the wiki from orbit and proceed with only the things it makes sense to keep
there. Then if we are linking out to wiki content I would probably link to
the actual wiki itself and not the transformed HTML copy of it (which we
should probably get deleted some day to clear out old stale pages since it
doesn't seem to remove things when you delete wiki pages).
I had a quick look at the source and had a couple of questions:
Am I right in thinking you now need to perform 2 generation steps to get
from the docbook source to having output that can be put up on the site?
This seems a little cumbersome, especially given the current single
generation step seems to make people too lazy to publish their changes on
the site as it is (though I guess we should just get around to automating
this with a build on the ASF Buildbot instances and link to that).
I noticed some html files that just look to be doing redirects with meta
refresh. Would it not be better to use an .htaccess file and have the web
server do the redirect? (Or in the case of the documentation page that I
originally noticed it in, just actually have a documentation page as
mentioned)
Finally, in the instructions for publishing people also need to check if
any pages have been removed/renamed, as just copying the new stuff over the
top wont show that and the old output will then be left to go stale (much
as with the transformed wiki html output).
Robbie
On 10 May 2013 17:39, Justin Ross <jr...@apache.org> wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't
> work because they point to things (such as a release tag) that don't
> exist yet.
>
> I'd like to hold a vote in about a week on replacing our current
> website. I'll have time for another update in the meantime, so please
> let me know about any changes you'd like to see. In particular, take
> a pass through the component page for the parts of Qpid you are
> familiar with. I'd love to get some detailed corrections and
> refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>
Re: Website update 4
Posted by Gordon Sim <gs...@redhat.com>.
On 05/10/2013 05:39 PM, Justin Ross wrote:
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
One other comment, on the 'discussion' page, it describes the two Qpid
lists as:
Users - Raise general questions, find out how a feature
works, or ask about any problems you encounter
Developers - Discuss the ongoing development of Qpid
I would like to suggest changing that to more strongly emphasise the
users list as the default place for all conversations. Specifically I
feel the description above for the dev list is too broad.
'Ongoing development' is very relevant to users and the fact that much
of this has occurred on the dev list in the past has led to a lack of
visibility into plans.
In my view the dev list should only be used for issues that are
obviously of little interest to most users. I can think of very few
conversations that would fit into that category.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
RE: Website update 4
Posted by Steve Huston <sh...@riverace.com>.
Looks very nice, Justin!
I don't see a link or description of qpidcomponents.org - since that's where users can get the Linux store, I think that's important. Maybe off the Downloads page like now?
Also, I am probably way out of date, but did I miss a discussion of changing the logo? I think it's cool, but don't remember discussing a change - it's probably me, but just asking.
Thanks,
-Steve
> -----Original Message-----
> From: Justin Ross [mailto:jross@apache.org]
> Sent: Friday, May 10, 2013 12:39 PM
> To: users@qpid.apache.org; dev@qpid.apache.org
> Subject: Website update 4
>
> Update:
> http://people.apache.org/~jross/transom/2013-05-10/
> Previous versions:
> http://people.apache.org/~jross/transom/2013-04-16/
> http://people.apache.org/~jross/transom/2013-04-03/
> http://people.apache.org/~jross/transom/2013-03-26/
> http://people.apache.org/~jross/transom/2013-03-13/
> Head version, for following things as they change:
> http://people.apache.org/~jross/transom/head/
> The source code and README:
> https://github.com/ssorj/transom
>
> Some bigger changes:
>
> - Added scripts to generate release notes
> - Added link to EAP 6 instructions in JCA page
> - Added QMF api doc
> - Add pdfs to book-generation scripts
> - Updated the messenger doc snapshot
> - Added messenger and protocol engine API doc in C, python, and java
> - Added messenger examples in many languages
> - Added make target and instructions for publishing content
> - Improved the developer center
> - Added 0.22 release content
> - Overhauled the scripts for generating release content
> - Added jms examples
>
> To better show the proposed launch state, I've made 0.22 the current
> release in the preview site. As a result, some of the links won't work
> because they point to things (such as a release tag) that don't exist yet.
>
> I'd like to hold a vote in about a week on replacing our current website. I'll
> have time for another update in the meantime, so please let me know about
> any changes you'd like to see. In particular, take a pass through the
> component page for the parts of Qpid you are familiar with. I'd love to get
> some detailed corrections and refinements.
>
> Thanks!
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org For additional
> commands, e-mail: dev-help@qpid.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org