Wiki for a software architecture document
Wikipedia has revolutionized the way information is generated, edited, and made accessible to various Internet audiences. Wikipedia, a publicly edited encyclopedia, is based on a concept of wiki where any user can edit any information at any time. This ad hoc approach sounds like a bad idea, but it may be useful for designing and documenting software architecture – democratically. The primary goal of the wiki solution is to make the system’s software architecture document a living document so that it can accessed and used effectively by all system stakeholders.
Compared with the industry’s “standard” approach to documenting software architectures (advanced word processor [MS Word], drawing software [Visio], and source control [CVS]) the wiki approach provides the following benefits. The document is accessible via any web browser, transclusion allows for repetition of information defined earlier in a document, source control and mechanism for merging & discussing changes are built-in. The wiki approach, however, suffers from lack of built-in image editing functionality. This means frequent copying and pasting from another image editor, which may or may not be available to all wiki user base.
The wiki approach is also a paradigm shift to managing software architecture. In an ordinary hierarchical organization software architecture design is done by a single person or by a very small group of software architects. The wiki approach levels the hierarchy and allows any team member to make changes. From one point of view the allocation of ownership may empower team members to contribute, but on the other side not a single person is accountable for the whole design. This may pose a challenge to a more traditional accountability structures and to people with fragile egos.
A technical note (TN) released by the Software Engineering Institute (SEI) shares the experience of using a wiki web-based tool by a small team of software engineers while working on a project for the Siemens corporation. For a more detailed discussion please see the TN page or TN in PDF.
Compared with the industry’s “standard” approach to documenting software architectures (advanced word processor [MS Word], drawing software [Visio], and source control [CVS]) the wiki approach provides the following benefits. The document is accessible via any web browser, transclusion allows for repetition of information defined earlier in a document, source control and mechanism for merging & discussing changes are built-in. The wiki approach, however, suffers from lack of built-in image editing functionality. This means frequent copying and pasting from another image editor, which may or may not be available to all wiki user base.
The wiki approach is also a paradigm shift to managing software architecture. In an ordinary hierarchical organization software architecture design is done by a single person or by a very small group of software architects. The wiki approach levels the hierarchy and allows any team member to make changes. From one point of view the allocation of ownership may empower team members to contribute, but on the other side not a single person is accountable for the whole design. This may pose a challenge to a more traditional accountability structures and to people with fragile egos.
A technical note (TN) released by the Software Engineering Institute (SEI) shares the experience of using a wiki web-based tool by a small team of software engineers while working on a project for the Siemens corporation. For a more detailed discussion please see the TN page or TN in PDF.
posted by Firebrand Architect® @ 9:37 PM
1 Comments:
At 7:27 PM,
Mark said…
I have not yet had the opportunity to try it, but Gliffy, a plug-in for Confluence, might offer a better means of incorporating diagrams in a software-architecture wiki.
Post a Comment
<< Home