wiki:Internal/Rbac/OrbitRbacDesign/DesignByWiki

Designing Using Wiki

Wiki pages like these constitute documentation of a work in progress. In the early stages, the wiki pages may well constitute all the work of a project. Although it is relatively easy to enter text and create links in a wiki, the first barrier in using one for a large project is determining how to structure the wiki pages to hold the work, i.e., breaking the on-going work into screen size chunks. Structure matters because wiki page references and links to attached documents encode the path to them.

In the initial research phase, it is useful to build up a list of references within which one can click to go to an associated pdf. These references could later be used in bibliographies of reports or papers written about the project. Wikis do not have the equivalent of BibTeX or Endnote. Using LaTeX and BibTeX and converting the .bbl intermediate file to a list of wiki references may be done with a Perl program bbl2wiki.pl in /home/hedinger/rbacrefs. The mkltx.sh shell script there will automatically open the wiki file with Kwrite with an encoding of utf8 to allow lines including Unicode characters to be cut from it and pasted into Trac wiki pages (that use utf8 coding internally).

Because this work is on an internal wiki page, the numerous PDF files accumulated while researching RBAC might be placed on an internal ftp server to make it easier to click through to access each one without the intervening "HTML preview not available" page when linking to attachments. Also, lots of attachments clutter the page.

It seems that only the Trac administrator can remove a Trac attachment. This raises the cost of playing around with where to put such attachments for references.

How does a group of people review a design in wiki format? Wiki pages do not print very nicely so that they may be reviewed in hardcopy form in a traditional meeting, and it seems a mistake to reformat wiki text with Word.

An incidental problem with a wiki or any hypertext document is that although it should be relatively easy to browse through one they are unlike a book that one can quickly flip through. Access to each page in a wiki requires a conscious click, and, if one erroneously assumes that one already knows or has already seen what is behind that door, one may well miss lots of information.

Like updating any document, updating a wiki design and implementation document as the project evolves will require occasional reorganization and continual efforts to keep the wiki up to date, i.e., reflecting current decisions. The wiki documents work done and decisions made primarily for later maintainers that may need to revisit certain decisions or add features.

Besides learning a new way to document ones work, there are other issues. Andrew Lincoln Burrow http://orbit-lab.org/attachment/wiki/Internal/Rbac/RbacResources/p77-burrow.pdf Bur04 states "The open and collective authorship of hypertext is the basis of wiki. It was pioneered by Ward Cunningham in the Portland Pattern Repository as a means to discuss software engineering strategies. In essence, wiki provides a model for collaboration, because it removes many impediments to shared authorship. However, it does not represent and restrict access to a document, and is thus not in a position to model the movement of a document from a narrower to a wider audience. Where creative ideas are at stake, this is often a barrier to the use of wiki."

"We observe two causes for wariness toward early disclosure. The first is the need to incubate ideas: premature comparison or criticism endangers the development of an idea, because every new idea requires a certain suspension of disbelief. The second is a conundrum of collaboration: we must share ideas to realize their value, but in doing so we diminish our own control. For these reasons, certain valuable types of collaboration require flexibility in determining access rules."

Last modified 13 years ago Last modified on 10/10/06 20:34:23