An engineer’s worst nightmare ? I get to spend today writing
documentation for the impending open source release of our translation
tools. I’m really excited about the release, but kinda wish I’d started
writing docs a long time back.
The code itself is already well documented from a programmers
point of view (aah, javadoc and Netbeans auto-comment, what would I have
done without you!) and the translation editor has had an excellent
user-oriented manual (in the form of a 56 page OpenOffice document) for
a while, but there’s not much documentation for our XLIFF filters and
not much technical material covering the overall design of the system.
So today, I want to sit down and start documenting ! I think I’ll
try to write it from the perspective of what I’d want to know if I
were a new programmer thinking about working on the tools, let’s hope
that’s a good approach. (Definitely also need to consider the users
point-of-view for the XLIFF filters though – need to do a little coding
in there to clean up usage messages, so perhaps I will get to write some
code today after all…)
I need to also get some html pages together with descriptions and
introductions to the tool we’re open sourcing, so I get to pretend to be
a marketing person for some of the day as well ! eg. Hmm, now what
font shall I use ?
As regards timelines for all this stuff, it shouldn’t be too long
now – though I don’t know more than that. We’ve got the final clearance
to release the code, so I’m now just waiting for a copyright statement
that I need to stick on the top of each file, then need to setup a
java.net project, and we’ll be ready to go !