> As was pointed out by Darrell Anderson, a documentation
> review board is needed. I have started a list on the
> Etherpad. This list is currently rather incomplete as I have
> not yet gone through any of the documentation, and I
> therefor do not have a thorough knowledge of everything that
> needs updating.
> 
> The list on the Etherpad should list known changes that need
> to be made to the documentation, and should allow anybody
> interested in maintaining documentation to claim the
> documentation for specific apps that they use on a regular
> basis.
> 
> The list of apps that is on the Etherpad is currently
> incomplete. I currently not have time to go through the
> packages to list all of them as I have some stuff in real
> life that I need to do, so the first several items on the
> apps list are just categories copied from the source
> downloads page. Feel free to expand them if you can.
> 
> If you do not trust your technical writing skills, perhaps
> you can simply check the docs for apps you are interested in
> and report needed changes that you see.

I have a lengthy check list that I am using to review the help files. I can post the list but I suspect most people will just get glassy eyed and walk away. My point is that this type of overhaul is more than skin deep. There is a lot to do. :)

With that said, most people will notice the many references to KDE rather than TDE or Trinity. Most of those references are actually through a DocBook entity, which serves the same purpose as a variable in coding. A single change in the entities files resolves those types of references. I'm in the process of running through a last test of my patches, which I have been using for a few weeks now.

After a successful build today I'll be pushing those patches to GIT. I'll post when I do. Most of the build issues that will arise will be with (applications) packages I do not (yet) build. The build failure is easy to spot and the fix is simple too (update the DocType declaration). I only need to be informed to provide a patch. Actually, I have already searched the entire source base and already know which apps need attention. I have those patches set aside. I won't immediately push the patches because I need to first build the packages. I'm not yet set up to do that --- I only build about a dozen of the extra apps.

Yet those types of fix are only superficial. As I mentioned, my check list is lengthy. Much longer than most people want to know. Revising and reviewing all help files and user guides is a long term project and not to be taken lightly.

For example, every online link found in a help file needs to be validated, removed, or changed. Resolving email addresses is another item. We don't yet have a style guide and that needs to be developed to ensure consistency among all help files. (Remember our discussion about "right-click"?)

Every image needs to be reviewed and updated when the image contains KDE3 remnants. I have already started pushing new images to GIT.

The main Help table of contents and the user guide table of contents all need reorganization.

Get the picture? Lots to do. :)

On the cheery side, as I have already started this process, after I push the initial set of patches anybody building packages will start noticing the changes. For example, just select Help from the TDE menu and the changes will be obvious. So yes, slowly the files are being transformed.

I believe we will be in great shape by the time R14 is released although I don't know whether every single set of help files will be reviewed properly. At the least, all of the little things like KDE -> TDE references, version numbers, copyright notices, etc. should be fixed before then.

I've been a tech writer for more than two decades and that allows me to provide a good foundation for editorial reviews, but this is not my project. Anybody who wants to help should. :) Technical correctness is something that everybody will need to help. I won't pretend to be a subject matter with many apps.

My check list is by no means complete. Currently I have listed only those things I have noticed. Please forward to this list or me anything that needs updating. I will add those items to my check list.

All source files are in DocBook markup. Don't worry about that. Just send comments and revisions in plain text.

I have been working on this quietly but I'm open to any suggestions anybody has with respect to organization.

Darrell