Wow, surprising to me how much time/energy/thought folks are putting
into the minor issue the file format of the design document. On the
other hand, I am happy that folks apparently agree with the much more
important issue of design doc role and content, as nobody seemed to have
remarks on that aspect.
So re the minor issue of the format:
We have tried design docs every way - as a wiki page, as content in the
ticket, as a separate attached document. I added into GitTrac the
custom markup {comment: xxxx} in support of adding comments into design
docs on the wiki. Like some of you, initially I also felt that putting
the design doc directly into the ticket was the best route.
But after actually having experience at the different format options,
using an attached .doc has worked out best, for several reasons. My
thoughts that led me to this:
1. It is self-contained. Yes, with discipline a wiki page could be
self-contained as well, but many folks need all the discipline help they
can get.
2. Design docs people wrote "in the wiki" have been universally very
weak compared to ones written as a separate document. I could
pontificate about why, but suffice to say there seems to be a different
mentality/formality writing into a wiki page (or email) vs a
word-processor document. A student writing a term paper does not write
it in their email editor, even though they technically could....
3. In no way shape or form do I want random "multiple people" to make
edits to a design document. Just the fact that on a wiki people feel
they can go in and edit it on a whim is a strike against using the wiki
for this purpose. While I definitely do want discussion/thoughts/input
re the design to be wide and open, I do not want _decisions_ about the
architecture to be a free-for-all. The design doc is a blueprint. I
want a well-thought-out design document written by one or two folks who
are very close to the problem, then I want it reviewed and ultimately
blessed by the architect responsible for that area of the code, and/or
(usually and) then reviewed/blessed by the tech lead (me). I want a
clear hand-off of the edit/review baton from developer to architect,
where there is one person (at a time) in charge of thinking deeply about
the issues. These design docs are publically posted on the ticket for
anyone to see and give input back to the developers/architects directly
involved to consider/think about. This process has worked. For
instance, most recently, look at #3218 where the remarks folks made in
the ticket on design doc drafts were considered, and many then made
their way into subsequent versions of the design doc.
4. Compatibility issues in practice have not happened using .doc files.
Note I did not say whatever ms word decides to use by default, I did
not say .docx files, I said .doc files. Between Word, Libre,
OpenOffice, everyone has access to software that happily edits .doc
files including proper revision tracking. And in practice compatibility
has worked fine for our 2-3 page documents that have very
simple/flexible formatting. Completely left to my own devices, I would
prefer LaTeX as well, but unlike LaTeX working with a .doc file is a
nearly universal skill.
5. Figures, remarks, and accepting/rejecting changes, has been easier in
practice w/ a .doc than on the wiki. Unlike a pdf, the "source" for the
doc is there. A .doc has greater longevity than any wiki anywhere.
6. Comments about time it takes to spin up word or open office are,
imho, inconsequential. Seriously, why do we care about the 15 seconds
that takes vs the many hours it takes to create the content itself
and/or insightfully review/think about it?
7. Miron is often interested in seeing the design documents, and on
occasion we get very insightful comments/thoughts as a result. I am
interested in continuing to benefit from Miron's 30 years of experience
here, and I am also interested in Miron having more awareness up-front
of architecture changes. For whatever reasons, Miron has a strong
preference to work in MS Word. I am not interested in spending my time
a) trying to convince him to use something different, or b)
cut-n-pasting wiki pages in and out of Word docs (I have also tried this
route in the past) in order to get his feedback. Especially so
considering that my own experience has shown that attached .doc files,
all things considered, seem to be the best route to go for this activity.
8. I agree w/ the comments about "having everything in one place", which
is why I put forth that the design doc should be attached to the ticket
(where checkins, milestones, remarks, status, etc all live) -vs- living
in some other area.
Hope the above helps folks see where I am coming from,
regards,
Todd
On 10/24/2012 7:12 AM, Matthew Farrellee wrote:
On 10/23/2012 06:17 PM, Alan De Smet wrote:
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.
+1
And if you care about Remark clutter, they can be integrated into the
Description and pruned.
Approaches storing the document in the repository do not allow for
participation by non-committers.
There is value in maintaining information in one location.
Best,
matt
_______________________________________________
Condor-devel mailing list
Condor-devel@xxxxxxxxxxx
https://lists.cs.wisc.edu/mailman/listinfo/condor-devel
