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
-- Todd Tannenbaum <tannenba@xxxxxxxxxxx> University of Wisconsin-Madison Center for High Throughput Computing Department of Computer Sciences Condor Project Technical Lead 1210 W. Dayton St. Rm #4257 Phone: (608) 263-7132 Madison, WI 53706-1685