trinity-devel@lists.pearsoncomputing.net

Message: previous - next
Month: April 2012

Re: [trinity-devel] kate - misc Naming and File Selector issues needing fixes

From: Darrell Anderson <humanreadable@...>
Date: Wed, 25 Apr 2012 20:35:28 -0700 (PDT)
>   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