[Interest] Harmonizing the Qt 5.x Documentation

Thiago Macieira thiago.macieira at intel.com
Tue Mar 11 17:19:14 CET 2014


Em ter 11 mar 2014, às 12:04:11, Matthew Woehlke escreveu:
> On 2014-03-11 05:01, Pasion Jerome wrote:
> > Short summary: We will be redirecting viewers of Qt 5.0 and Qt 5.1
> > documentation to "Qt 5" documentation. Subsequently, we will remove the
> > 5.0 and 5.1 documentation from qt-project.org and we will place future Qt
> > 5.x documentation in "Qt 5" (http://qt-project.org/doc/qt-5/).
> 
> How am I then supposed to find the 5.x documentation if I am developing
> an application against 5.x but the latest release is 5.y?

First of all, you should read the latest documentation. It contains the 
notices saying when classes and methods were added so you will know whether 
they apply to you. Plus, you get updates and fixes for the docs that have 
happened since that release, as well as comments by users on the website.

Second, if you really want that documentation, it came with your 5.x release. 
Just load it in Creator or Assistant.

> It's common practice to keep old documentation available so that users
> can have a correct view of the state of the software /as of the version
> they are using/. If you don't do this, you *MUST* accurately document
> every *change* (not just additions) between versions and have that
> documentation clearly visible in the documentation of the affected
> classes/methods/etc. (Plus, I know from experience that \since is easily
> overlooked.)

We document only additions. Improvements to the docs don't make sense. Bugfixes 
to the code don't need documentation either: if you're using intentionally an 
old version, you are subject to corrected bugs and you know it. I could agree 
to behaviour changes, however rare: whenever there's a behaviour change, it 
should be documented in the class docs.

> I would also encourage doing like python.org and adding a widget to
> select the documentation version. You could also add a big noisy warning
> to the historic documentation pages.

That would be nice. MSDN does the same per MSVC version too.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center




More information about the Interest mailing list