Last night in IRC it came up about documenting both KDE and Gnome walk-throughs when writing docs. This is sort of aimed at John and his group working on KDE stuff already, do you want KDE docs written separate? For example would it be OK to include a menu walk-through for both Gnome and KDE when writing an independent doc (e.g. not attached/related to the DUG)? My thought is that a single doc that includes all the relevant instructions for a particular task would be good. However, if the larger idea is to have 2 separate doc trees (i.e. Gnome and KDE) then this would not be a good idea.
-Jason
On Tue, 2007-11-27 at 10:39 -0500, Jason wrote:
Last night in IRC it came up about documenting both KDE and Gnome walk-throughs when writing docs. This is sort of aimed at John and his group working on KDE stuff already, do you want KDE docs written separate? For example would it be OK to include a menu walk-through for both Gnome and KDE when writing an independent doc (e.g. not attached/related to the DUG)? My thought is that a single doc that includes all the relevant instructions for a particular task would be good. However, if the larger idea is to have 2 separate doc trees (i.e. Gnome and KDE) then this would not be a good idea.
Obviously this is not clear enough. Is there somewhere good in the wiki we can put down this rule? Under DocsProject/WorkFlow?
I think this is just knowledge shared on the list and not yet documented. :) The idea is to have all you need in one doc, and in a consistent manner that is useful. Also, this gives you a cascading pattern of importance, so if you have to fall short in content or need to bring in help, it is easier to assign them to a broad range (all KDE, all CLI, etc.)
So, a chapter and sections could go like this:
= Cool Tech =
Summary.
== Using Cool Tech for Task 1 ==
== In GNOME ==
== In KDE ==
== Using CLI ==
== In XCFE ==
...
(It's not necessary to make separate == sections == for each, that could just be the order used within a single section.)
That means we prioritize documenting by the default (GNOME), the next popular (KDE), the useful anywhere but not a GUI (CLI), and the last popular/used (XCFE).
By using a consistent order, if anything is missing we can either put a NO CONTENT WRITTEN mark or otherwise leave it out, and hopefully give the reader enough clues to not get lost. As ugly as it sounds, it seems like it's necessary to be useful to the widest range of potential readers.
Let's confirm or fix, iterate, and get a consensus on what form we want this to take.
- Karsten