Re: [Condor-devel] How/when to write a Design Document

[Alan De Smet <adesmet@xxxxxxxxxxx>]

Timothy St. Clair <tstclair@xxxxxxxxxx> wrote:
> Why attach a separate MSFT.doc to a ticket, vs. making the
> ticket be the design doc, and having all the sections you
> mentioned?

Agreed.

A Word document adds unnecessary complexity.  You can run into
compatibility issues (be sure to save in Word 2003?).
In-document revision control may not work to varying degrees
depending on the software used and the configuration.  Resolving
conflicts if multiple people edit simultaneously is far clumsier
in a Word document than in a Wiki.  (Not that CVSTrac is great at
conflict resolution, but worst case you can extract the
unformatted text for the versions in question and do a merge in
your favorite 3-way merge tool.)  The mere existence of multiple
copies creates the possibility of accidental forks.  Keeping the
document self contained is a matter of discipline, moving the
documentation to its own file is only a marginal help.

Other proposals, in my order of preference:

1. The design document should be the "Description" section of the
ticket.  That the Remarks may grow without bound is irrelevant,
since you only need the Description at the top.  The document can
and should be updated to reflect reality.  This eliminates any
redundancy, the design and current plan are in one and only one
location.  Someone interested in older information can look in
the History, which is kinda sucky (it's diffs), but good enough
given how rare doing so is.

2. The design document should be it own wiki page.  This keeps it
separate from the Remarks, which is a bit cleaner.  You also get
a nice, formatted history that you can link directly into.

(For 2 and 3, I believe images are rare enough that the existing
ability to attach a file and display it are Good Enough.)

3. The design document should be plain text in the Condor
repository on the branch it is planned to go into.  "Plain text"
might literally be plain text, but if nicer formatted versions
are desired we can use TeX, Markdown, or another simple
formatter.  This puts the documentation right next to the code,
leverages our existing revision control system, and provides easy
access to older versions.

-- 
Alan De Smet                 Center for High Throughput Computing
adesmet@xxxxxxxxxxx                       http://chtc.cs.wisc.edu