Replace obsolete documentation with contemporary notes
-
I've been enjoying the addition of notes to the Qt documentation quite a bit, since those helped me avoid certain sub-optimal approaches to coding in Qt.
Logically, this brings me to a question:
Why have all the outdated, obsolete and sub-optimal documentation in tact instead of simply UPDATING it?
Sure, the notes help prevent mistakes, but reading the wrong approach and then scrolling down to find out it is wrong seems to be sub-optimal itself. Why have something more or less wrong, followed by the adequate solution?
Wouldn't it be better to have obsolete coding examples simply replaced by the right ones? This will save people the time and brain clutter to learn the wrong way of doing things, and since the notes are in the very end, some people might not actually even reach those and realize the documentation offers a sub-optimal routine at all, which will result in permanent bad coding practices.
Seeing how note contributors are also top forum contributors, those people can be trusted to keep the documentation up to date. I certainly don't see any loss in removing obsolete and sub-optimal routines and replacing them with the right ones.
-
First, don't moan too much, Qt has one of the very best documentations out there. I did code in a few environments, and doc were always much worse than in Qt.
Second, this forum and it's doc clone is pretty much separate from real development process of Qt itself. In order to point out an error in doc to developers of the framework, one has to fill a bug report on JIRA. There it is almost certain to get some attention. Devs are busy as they are, and don't have too much time to look at multiple sources of information about bugs.
Third, Qt is huge (close to 1000 classes, IIRC), and changes a lot. It is hard to keep everything absolutely up to date, especially when some people drop out, new come in etc.
Fourth, you are probably referring to Qt4.7, which is currently available here. Remember, Qt4.8 is about to be released, and will have some docs updated. Qt5 is in the making, and will also come with big documentation updates.
So, I we spot a suboptimal piece in docs, we can either create a bug report and leave it at that, or create a bug report, then correct the doc ourselves and upload a patch on Gerrit that fixes the issue.
-
First of all, I am not moaning, I just happened to open two "random" articles from the Qt documentation, and accidentally or not they both happened to provide sub-optimal coding examples as well as notes indicating that and offering more adequate solutions.
I don't say you should go through the entire documentation and fix everything that is sub-optimal, but in the cases of notes people have already gone through the effort to identify and correct those, I just happen to think those corrections are better off in the actual article instead of stuck in the very end.
And sure, I could simply start off from the end in order to see whether what I am about to read is adequate or not, but reading from the end is not standard practice, even people who read right to left or vertically start and the top and go down.
It is somehow wrong to read and entire article and then in the end you see "now that you have read this entire article it's the time to learn that it is wrong, and here is the right one"
-
True, that. I do agree fully, it should be done, but I just wanted to point out it's not that simple. The actual Qt documentation needs to be updated, and that resides inside the source code of Qt.
Oh, and about "moaning" - well, I might have chosen a wrong word for that. "Complaining" would have been better. Either way, it was not intended as a reproach, just a way of starting my reply in the right place (that is pointing out the general quality of the documentation). Sorry if you took it personally.
-
I am afraid "complaining" is just as inappropriate as "moaning". I would neither moan, nor complain about something someone else did and provided for my use free of charge. In fact I don' think words can express my gratitude towards the trolls and all the outstanding job they've been doing through the years.
It is just that the Qt library is "yet another truckload of technical information" I need to cram inside my tiny and already bursting at the seams mind. And it really helps learning things the right way the first time around instead of learning how to use a class just so that you later learn what you learned is wrong - this increases the strain for me, since besides remembering the adequate solution I also have to remember to forget the wrong one, if you get what I mean.
If the imminent 4.8 release is about to fix those then fixing it now will be a wasted effort, but if not, then the notes already provide the fix, all that is needed is a way to give the adequate solutions higher display priority.
-
Open Government of Qt is in the wild just for about a month and a half (it started in October, shortly before DevDays in Munich). From my understandings, right now it's more the actual coders that are contributing to Qt. But I'm pretty sure that over time we will see plain documentation bug fixes too. I personally still didn't have time and muse to setup everything, so leaving a DocNote is a quick an easy alternative to publish a hint at all.
-
Well, we could organise a sort of "documentation helper group" here on DevNet, that would aggregate those notes and occasionally apply fixes to Qt's QDoc source code - so that the documentation gets better where needed. This would give Trolls and Contributors more time to work on their problems.
-
Don't you try logic on me!
Joking, sorry ;) Of course, you are correct. Not everybody would have to be a contributor, in fact. To keep number of commits down, they could be performed by less people than the number of those finding "bugs" in documentation. And to be honest, I did mean contributors devising new features.
Aaaanyway, just theorising, cause I'm in a kind of "Friday" mood. An idea that might catch some momentum and do some good, or - most probably - wither and die miserably in darkness of the past.
