Re: GNUism in groff tests, was: pic anomalies

[Larry Kollar]

G. Branden Robinson <address@hidden> wrote:

> A rock star cowboy with a smoke machine to conceal the spit and bailing
> wire in his implementation is hailed as a genius.
> 
> An engineer who spends effort building a robust system is regarded as a
> cost center.

Can I steal these quotes (with attribution)?

The software engineer who was maintaining our DITA-OT transforms at work
bailed for greener pastures earlier this year, so everyone is looking at me to
apply my own bailing wire to the code base until we hire someone else (and
I have actual documentation work to do). Back to that in a moment, but our
testing methodology seems to be:

1) Feed a “pilot book” that has examples of all our elements to the transform
and look for trouble. Fix, try again.

2) Upload the code to a “test” transform folder in our CCMS and throw it to the
wolves (i.e. hope the other writers actually try it out to see if it does what 
it’s
supposed to).

3) If nobody sends an “oh $#¡+ this is b0rk3d” email after a week or so, copy
the code to the “production” transform.

If none of that makes sense… well, being able to code a DITA-OT transform
looks really good on a tech writer’s resume, but if you don’t have to… don’t.

Anyway, back to the code base. We have seven (count ‘em, SEVEN) different
variants of PDF output. I’d taken the primary PDF to beta before the software
engineer came on board, and I was happy to let him run with it. Then, we
started getting requests for various side-document outputs; he ran with them
all (the 4x4 inch quick start guides, that used to be done in InDesign, I think
is pretty much Peak XSL:FO). But there are several cases of “spit and bailing
wire” that I’ve found while trying to maintain and update the transforms:

1) The biggest is inconsistencies in outputclass names. These are a way to
get some formatting control where needed, without letting people run amok
and going completely unstructured, but it’s not good to have one transform
expect “MatchList” and another “matchlist.” All that needs to be fixed. We’re
supposed to be able to reuse stuff, adapting to different formats, and it can’t
happen if it’s not consistent.

2) Each transform has its own strings (things like “Note:” that are auto-
generated in whatever language is needed). Those need to be abstracted out
to a common base. Our HTML transform had 5 or 6 different files that needed
to be changed when we update the copyright year… which is probably the
first thing I’ll need to do when I go back into the office tomorrow. I did 
manage
to get that down to 3 files. But I need to do it for each language, for each PDF
transform as well.

3) Same deal with icons and company logos. As we got bought last year, and
I had to deal with rebranding in the runup to the holidays, I’m still smarting
from that one as well. Only the HTML and two PDF transforms got done;
there’s all the others to fiddle with.


I can partly get the cowboy motivation—that demo has to work, at all costs,
and everyone’s depending on him (usually a him) to make it happen. And if
we don’t expect the cowboy to help turn the demo into production code, he
won’t take the necessary steps to make it maintainable.

So at the very least, I’ll be writing specs for the future software person to
handle the re-architecture. We also need to look at collapsing the number of
transforms we’re supporting, which is a management task. But this is my
major source of heartburn with any complex system: it’s far too dependent
on one or two experts, and one layoff or re-org can send the whole shebang
to the legacy bin. Long gone are the days when most of the staff knew *roff
well enough to tweak macros where needed. I could do the work, if someone
else picked up the documentation work, but I’ve been the only person who
has touched that base since 2002. It now is roughly 2000 files, and produces
four versions of the firmware guide. As I told a former manager, “we knocked
down our silos, but nobody is stepping over the rubble.”

Sorry about the long rant, if anyone has read this far, but I all too well 
understand
how easy it is to skip that boring testing phase and roll out the Shiny! New!
Version! of code. Especially when half your user base is clamoring for release,
and the other half is suggesting more enhancements. Automated tests are
perhaps our only hope.

        Larry