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-unsubscr...@qpid.apache.org > For additional commands, e-mail: dev-h...@qpid.apache.org > >
