> -----Ursprüngliche Nachricht----- > > I do think this criticism is valid for some points: I too have often stumbled upon > old versions of documentation pages when googling. Sometimes (as is the case > with removed or renamed pages) simply updating the version in the URL just > throws you back at the root (for example when changing the 1.2 in > manual.qooxdoo.org/1.2/pages/development/variants.html to 2.1, I get > redirected to http://qooxdoo.org/docs, which is not very helpful and will fail to > inform me of the fact that variants have been removed [the 1.4 version would > inform me of that but how would I know this beforehand?]). > > > > It could be very helpful to either have a more intelligent redirection > mechanism, a canonical <link> tag (to nudge search engines to the latest version > of a documentation page), or a switcher on each page to help the user to select > the correct version. > > Well, yes, you hit on a couple of topics. > > - As mentioned in another mail we'll try to improve search results from Google > through site maps or similar. We do have canonical links, 'current' and 'devel', > for the manual and the released demos, so ideally they should come up first in > search results (which they currently don't). > > - I agree that redirection to qooxdoo.org/docs on a 404 while being in a > concrete manual is not very helpful. The top-level page of that manual would be > much better. Please open a bug for this.
http://bugzilla.qooxdoo.org/show_bug.cgi?id=7349 > > - A switcher between versions of the manual is easy, as you said (just change the > version string in the URL). Getting you to the "correct" page in another version is > an entirely different thing. It would require cross-linking between versions, > making up for any change in contents and/or structure of the manual. I'm afraid > that would be too much for us to deliver. It might also require that we make > changes to the manual of a long-released version just because we have released > a new one. I figured as much. However, a version switcher that did not account for renames would be great even as it would allow me to quickly see that 1.5 was the last version where the variants page has existed, I could then switch to that and it would show me the deprecation notice. > > - There are various aspects to the "variants" issue. One thing is procede from a > user guide section like development/variants.html to the reference section like > tool/generator/generator_config_ref.html, to learn that there is no "variants" > config key anymore. That's generally a good idea: If you are looking for > something specific think of the reference this concept is from, and then look > there. For configuration issues this would be the mentioned > generator_config_ref, for the framework API the Apiviewer, asf. > > - This still doesn't answer questions of the form "What happened to ...?". If you > make a big jump like from qx 1.2 to 2.1, a lot might have changed. We try to > keep manual and Apiviewer self-contained, and do not maintain transitional > information there. Transitions are generally documented in the release notes, > and a search for "variants" on the homepage brings up the release notes for 1.4 > as first hit (it might not be so easy for more general terms). Generally, if you > want to catch up with changes between qooxdoo versions, best is to read > through all the intervening release notes. We put a lot of effort into them, there > is usually a highlights section, and then all user-visible changes grouped by area. Yes, kudos to you for keeping such great changelogs. However, they can be a bit overwhelming and going through every one when researching a small feature isnt the first thing Id do in a lot of cases. So I would waste a lot of time trying to implement some technique Id found on an old manual page and only when that hasnt worked would I start trying to research what might have changed in the version Im using. > > HTH, > T. -- Raphael
smime.p7s
Description: S/MIME cryptographic signature
------------------------------------------------------------------------------ Precog is a next-generation analytics platform capable of advanced analytics on semi-structured data. The platform includes APIs for building apps and a phenomenal toolset for data science. Developers can use our toolset for easy data analysis & visualization. Get a free account! http://www2.precog.com/precogplatform/slashdotnewsletter
_______________________________________________ qooxdoo-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
