If your change is an enhancement (new feature) or large bug fix, you will need to author and attach a design document to the ticket page for architecture review and get it approved before code contributions will be accepted. It is typical for a design document to go through several revisions. Although they are generally pithy and to the point (2 or 3 pages is typical), the generation and review of a well thought-out design document can be a time-consuming undertaking. But we feel it is necessary to ensure the architectural integrity and correctness of the code base, and ultimately the time spent writing a design document is time well-spent.
-We require the use of =.docx= files (either ms word or
-open office) to ensure they are self-contained and to leverage revision tracking as they are passed around for
- review and refinement. Two to four pages is typical, but could be more
+Two to four pages is typical, but could be more
or less depending on the situation.
+As of July, 2013, new design documents should be Google Drive documents to ensure they are self-contained, have revision tracking, and reduce the risk of version skew. See GoogleDriveWisdom for details on usage.
+
+Older design documents are =.docx= files (either Microsoft Word or
+Open Office/Libre Office) to ensure they are self-contained and to leverage revision tracking as they are passed around for review and refinement.
+
{subsection: Outline of a Design Document}
A design document has three major sections; each is outlined below. While you can assume that the reader is familiar with pre-existing design and implementation of the code, this is not an email or wiki post - the document itself should be self-contained and able to "make sense" on its own. This is part of the reason we require a separate =.doc= file. A developer five years from now, who was not involved in a recent string of email discussions or lacks access to pages of ticket remarks, should be able to read the document on its own and gain insight and understanding.
