All,
While waiting on the rebuild of tdelibs and tdebase with full symbols, I was poking around in kate and came up with another couple of fixes that are needed.
The first is a simple khelpcenter name change for Settings > Application > File Selector. The khelpcenter name for this section is 'The Filesystem Browser Page' instead of being the 'The File Selector Page'.
It looks like there was a name change somewhere along the way that was never implemented in the help files. Looking at the other entries in the help file, they correspond fairly closely to the settings dialog. Here are some other changes for the help file needed just to dot [i]s and cross [t]s:
General - Meta-Data -> Meta-Information (who knew..)
crap - that's as far as I got - first time that happened - the whole desktop locked. It had been running in virtualbox since April 17 without any issue:
18:03 alchemy:~/tde/tmp/tdebasep/patches> ps aux | grep -i virtual david 14521 0.0 0.0 7788 828 pts/1 S+ 18:04 0:00 grep -i virtual david 31843 0.0 0.5 458276 20300 ? Sl Apr17 2:13 /usr/lib/virtualbox/VirtualBox david 31858 0.1 0.1 71364 4148 ? S Apr17 14:22 /usr/lib/virtualbox/VBoxXPCOMIPCD david 31863 0.2 0.1 270528 6764 ? Sl Apr17 23:31 /usr/lib/virtualbox/VBoxSVC --auto-shutdown david 31985 5.2 22.4 1502648 883052 ? Sl Apr17 609:27 /usr/lib/virtualbox/VirtualBox --comment Archlinux x86_64 --startvm b0896a45-eafe-4029-8268-a0fd89cd7b4b --no-startvm-errormsgbox
The hard drive on virtualbox is thrashing away -- looks like I'll have to kill something hard. Will report back...
While waiting on the rebuild of tdelibs and tdebase with full symbols, I was poking around in kate and came up with another couple of fixes that are needed.
The first is a simple khelpcenter name change for Settings > Application > File Selector. The khelpcenter name for this section is 'The Filesystem Browser Page' instead of being the 'The File Selector Page'.
It looks like there was a name change somewhere along the way that was never implemented in the help files. Looking at the other entries in the help file, they correspond fairly closely to the settings dialog. Here are some other changes for the help file needed just to dot [i]s and cross [t]s:
All help files need a thorough review. As a group I don't know how we are going to perform those reviews. There is a lot of grunt work involved. People need to read, compare to the actual app settings, validate statements and claims, etc.
Not to mention that the translated versions are in worse shape.
I have done a bunch of cleanup, yet we have no style guide to guide everybody.
I want to implement a simple policy of not updating the docbook sources to use the new version/date entities unless the contents have been reviewed and updated. The entities provide a dynamic means of reflecting the current release number (R14) and release date.
That means each handbook retains its static version and release date information, such as version 0.1, released Jan. 2001. That will be our notice to ourselves (and users) the document has not bee reviewed and updated.
I'm using the entities for three or four help files. I have started reviewing those documents. Under my proposed policy I should not be using the entities, but I need a few files using those entities to ensure they are working and compiling correctly.
There really is no way to update the help guides unless everybody in the entire Trinity community decides to help. There is too much for only three or four of us to handle. Doesn't matter who picks which document to review and validate --- they all need desperate attention.
Darrell
On 04/25/2012 06:32 PM, Darrell Anderson wrote:
There really is no way to update the help guides unless everybody in the entire Trinity community decides to help. There is too much for only three or four of us to handle. Doesn't matter who picks which document to review and validate --- they all need desperate attention.
Darrell
Darrell,
I agree, it has got to be a divide and conqueror strategy. Something like:
(# of help files)/(number of volunteers) = numDocs per volunteer to review
The denominator is critical :) Looking at where we are on R14, I see:
(1) continue to taper changes leading to code freeze;
(2) fix bugs, review status a May meeting (may want to set a May 5 & May 20) set of meetings (I didn't look at calendars - just guesses for example)
(3) finalize doc review, etc..
(4) release.
I agree, it has got to be a divide and conqueror strategy. Something like:
(# of help files)/(number of volunteers) = numDocs per volunteer to review
The denominator is critical :) Looking at where we are on R14, I see:
(1) continue to taper changes leading to code freeze;
(2) fix bugs, review status a May meeting (may want to set a May 5 & May 20) set of meetings (I didn't look at calendars - just guesses for example)
(3) finalize doc review, etc..
(4) release.
I build all but a few of the applications. Thus I more or less have a full selection of Trinity apps. On my system:
locate index.cache.bz2 | wc -l
yields 309 documents.
How many are inaccurate and need review? Presume 80%, or 247.
How many help book volunteers do we have? One (me).
The reality: people who choose tech writing as a career enjoy this kind of work. Me. :) Everybody else in the world detests documentation. Software developers seem unusually adverse to helping with documentation. :) In other words, don't expect the number of volunteers to increase much. :)
If we want to block a time period for documentation reviews then I'm game. Otherwise we fix the books as we go.
If we release a solid R14 --- really solid, then possibly thereafter more of us can spend time reviewing and updating the help files.
To people who have a passion for a particular app, they could start reviewing on their own and submit changes.
Editing the docbook source file only requires a decent text editor with syntax highlighting and a nominal degree of care to pay attention to the tags. Quanta Plus can perform tag checks if anybody is interested.
For nominal changes, editing the docbook files is not required. Copying and pasting to a text editor from the help files and then editing is sufficient. Large scale editing in that manner would be cumbersome to merge to the docbook files. At one time I proposed a KWord template that used style tag names matching the docbook markup tags, which would help exporting to a quasi docbook format, but no such template exists.
Darrell
-
Darrell Anderson -
David C. Rankin