[Qt-creator] Request for comments.... help... QtCreator tutorial

[André Pönitz]

On Thu, Sep 05, 2013 at 11:16:02PM +0200, Guido Seifert wrote:
> 
> > I am certainly not opposed to have a bit of exposure on SO, but for the
> > purpose of documentation it sounds rather odd.
> 
> Seems to be accepted on SO. And it looks like I am not the first with
> this idea. Though I must admit, that I still wait and see, if my post is
> closed for some obscure reason, before I add another one. 
> 
> > You gave yourself a perfect example that even high-quality
> > documentation bit-rots rather quickly if it is not kept close to and
> > maintained together with the source.
> 
> Yes.... but honestly, the documentation about the QtC internals is thin.
> Far below the great Qt docs.

There is really not much sense in documenting application _internals_ that
are explicitly meant to be left open to allow for rapid adaptation. It's
only with the upcoming 3.0 that we will promise some kind of internal
interface stability, and I would expect the volume on docs grow with
that as there wouldn't be so much removed because it's outdated...

> With the SO docs there is at least a chance, that volunteers can jump on
> and add to my docs, or even edit them when I make a mistake. [...]

The same volunteers could contribute to the "real" docs. Setting up an
account on Gerrit is a one-time activity. Even a documented one ;-)
Yes, it's quite a bit more work than adding a SO comment, so if that's
the problem we could perhaps discuss how to make this kind of contributions
easier.

> And 'kept close to and maintained'...Did not really happen,

What is there is meant to be up-to-date, and - at least that's my
perception - it usually roughly is.

> ... else I wouldn't have had so much work to get into the code. Please,
> don't take this as criticism. A Qt like documentation for QtC would be
> overkill. Qt and QtC have different requirements. But this means that it
> might be necessary to try several methods of documentation and see which
> works best. SO could be one of those methods.

You could certainly try. It's still somewhat sad to see this kind of
intentional framentation, especially since such documentation can never be
incorporated into the sources. We can't go out and grab random content
from the net, no matter how good it is.

Anyway, it's your choice, and - do me a favour and make sure to mention
the version of Creator your documentation refers to.

Andre'