On 04/17/2013 03:13 PM, Raphael Schweikert - Vertec AG wrote: >> -----Ursprüngliche Nachricht----- >> Von: thron7 [mailto:thomas.herchenroe...@1und1.de] >> Gesendet: Mittwoch, 17. April 2013 11:04 >> An: qooxdoo Development >> Betreff: Re: [qooxdoo-devel] Questions & Wrong information on the website >> >> On 04/17/2013 09:20 AM, tedi tedi wrote: >> >> I wanted to create a documentation for my package, just to make the >> warning go away, so I found this page: >> http://manual.qooxdoo.org/1.3/pages/development/write_api_documentation >> .html >> >> There's something wrong with it: >> At section "__init__.js Files" you say: "In order to fill this gap you >> can >> add a __init.js__ file to a package.". The file I had to create was a .js >> file, not a >> .js__ file. So please update the sentence to "In order to fill this gap you >> can add >> a __init__.js file to a package.", since the filename in the section title >> is the >> correct one. > 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. - 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. - 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. HTH, T. ------------------------------------------------------------------------------ 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 qooxdoo-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
