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