On 24 May 2013 12:30, Justin Ross <justin.r...@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 > <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. >
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-unsubscr...@qpid.apache.org > For additional commands, e-mail: dev-h...@qpid.apache.org > >
