81 - write SDD document
What is the issue?
The software design and implementation of SpeakinSpell is not documented, but should be.
It's growing large enough that it's beginning to merit a design document for my own reference purposes, as well as to introduce a new dev to the team if anyone ever volunteered, and/or to record the design description in the event that I ever abandon this project and some other dev picks it up in the future to continue maintenance.
An SDD is a Software Design Document. It should cover the high level architecture of the system and descriptions of subsystems and their assigned tasks and architecture etc.
- 4 comments
- 4 comments
Facts
- Last updated on
- 22 Nov 2009
- Reported on
- 07 Oct 2009
- Status
- Fixed - Developer made requested changes. QA should verify.
- Type
- Other - Some other kind of issue
- Priority
- Low - Might slip to a later milestone.
Reported by
Possible assignees
-
- Manager
- Author
-
- Tester
-
- Translator
-
- Translator
Votes (Total: +2, Average: +2.0)
-
Votes +2
- #4
rismisner Sun, 22 Nov 2009 11:00:10correction to a comment below: "Ongoing tickets are NOT needed to remind me to pursue ongoing maintenance" of this document in general. But I'm open to specific requests, was my point.
- #3
rismisner Sun, 22 Nov 2009 10:58:36First released in 3.2.2.13
- #2
rismisner Sun, 22 Nov 2009 10:58:12I was in a writing mood today so I created SDD.doc.
This is a Microsoft Word document that describes quite a lot about the SpeakinSpell architecture and design. I created it in MS Word 2007, but saved it in the backward compatible Word 97-2003 *.doc format (instead of the newer *.docx) for wider compatibility for people who don't have the latest MS Office.
As limiting as MS Word is, I'd rather not deal with exporting it to another more portable format like HTML, or the markup language used by the wowace project site pages here. It's much easier for me to maintain as a Word doc, and Word also supports some good change tracking features to facilitate mutual collaboration on this open-source file.
I'm going to go ahead and close this ticket for now given that an SDD has been created. Ongoing tickets are needed to remind me to pursue ongoing maintenance. However, if there are any further specific requests for new topics to cover in the SDD, or pleas for a new file format, go ahead and reopen the ticket with applicable comments.
- #1
Aetharan Thu, 08 Oct 2009 01:48:22You'd be one of the first Addon authors I've known to follow this good practice. I've always been told that everything should be documented, from in-line and block comments in the code explaining what a method is doing to a design document explaining what the program is doing (often in the form of a flow chart before the first line of code is ever written.)
As part of my effort to learn LUA, I intend to read through SnS when I get the chance. The better-documented it is, the more useful it will be as a learning tool.