Details
-
Suggestion
-
Resolution: Out of scope
-
Not Evaluated
-
None
-
None
-
None
Description
Edit: Made problem statement more general, with different solution candidates
Background
Doc notes have many benefits. They are:
- Easy for the community to contribute to
- The web interface is much more approachable than Gerrit, for a newcomer
- Instantly visible to, and easily findable by, the community
- C.f. Contributing via bug report
- A very logical place to share useful tidbits that don't quite belong in main documentation
- E.g. Clever hacks, use cases
They also have some weaknesses. They:
- Are not integrated with offline docs
- Can't see/edit/write doc notes in Qt Assistant, or Qt Creator's integrated docs
- They are broad, and apply to a whole page
- The ability to attach a note to a particular member function could be helpful
- Can possibly get left behind when Qt is updated
- (I'm not sure if a doc note's "Target version" list is automatically updated when a new Qt version is released – major or minor)
Problem statement
We want to maximize the benefits and minimize the weaknesses of doc notes, as listed above.
Solution candidate 1
Follow the lead of PHP docs, and make doc notes accessible from offline sources (especially the IDE)
Solution candidate 2
Periodically review doc notes, and integrate appropriate bits into the main documentation.
Website features that can assist the Qt Documentation team with this process are:
- An overview page, to see a list of all doc notes (
QTWEBSITE-471) - Ability to flag the "integration state" of a note (taking into account the dynamic nature of doc notes – they can be updated at any time)
- "Not yet reviewed"
- "Reviewed, will not be merged"
- "Merged into documentation"
Other considerations
- Permissions and credits
- Qt DevNet points
References
Original discussion: http://lists.qt-project.org/pipermail/development/2012-October/006890.html