The Dream Documentation
The technical documentation we endeavor is measured by the following qualities:
· Product proficiency – how much of the product is covered and to what depth.
· Topic accessibility – how easy is it to find what you are looking for within the documentation
· Quality of the text – how well is the text written
Documenting an application traditionally evolves two types of contributors:
· Technical staff – they know the application, as they design, develop and implement it, but they can’t write, or won’t write
· Technical Writer – can write, doesn’t know what to write
Of course, some technical staff writes well, and some writers know what they are writing about. Yet, there’s a fundamental gap between the two. (If a technical writer knows your application as profoundly as you do, you are in serious troubles; if someone writes as good as a professional writer, then the writer isn’t too professional…).
As a result, the writing process circulates the paper (usually a user guide or an on-line help) between the writer and the techies. Bouncing back and forth, the document both gets closer to the application it describes, and becomes more articulate.
Finally, the documentation airs way after the product and is always incomplete.
Wiki attracts writers.
This is its major property and the one that has made it so notorious.
The platform itself is a plain website, with the ability to create a new page from within any other page. Its strongest feature, though, is that pages can be created and edited by any user.
The Wiki technology was invented in 1995 and has become famous thanks to the successful Wikipedia. Founded in 2001, Wikipedia is an internet encyclopedia that had severe troubles writing and editing articles. Its founder, Jimmy Wales, had opened it to the public, using the Wiki technology. By 2004, Wikipedia was twice as big as the Britannica, until then was the largest encyclopedia ever.
The Wiki technology attracts writers for the following reasons:
· Ease of use – there is no real reason why the Wiki mark-up language appeals more than HTML, but it does, and writers find it easy to use.
· Focus on writing – a simple DOC paper, let alone a 200pp. user guide, distracts the writer from writing, wasting his/her time on templates, styles, formats, macros… you name it. Wiki just doesn’t to that.
· Easy collaboration – collaborating an office document often results in comments in five different colors, and a colorless guy who is assigned to clean up the mess. Wiki allows for endless editing by multiple users, seamlessly proofing the text.
· Transparent editing – editing makes better writers (and editors). The Wiki way of editing makes writers care more for what they write, “defend” their text, comment to editor’s notes and quickly become better writers.
Basically, the Wiki site follows the form on the current on-line help. This means a tree-based structure (for details, see AppSight 6.0 Documentation Work Plan) with an index, a search mechanism and links that go back and forth.
A Wiki-based website features an editing page for each content page. These pages are dedicated for discussions that follow the process of writing. Additionally, there is a “Recent” mechanism that lists all recent edits.
Action Item 1 State the site’s structure for 6.0 documentation
Aside the Edit and Save buttons, the page controls include some 10 mark-up tags, and, usually, a Wysiwyg. There is no use to mimic MS-Word’s complexity, so there are no macros, styles, and usually no way to apply the text with 17 different colors, including 11 different shades of navy blue.
Action Item 2 Add a recommended page structure for the wiki-based help site.
Providing technical personnel with full access to the documentation emerges an immediate fear of anarchy. Intuitively, freedom goes hand in hand with disorder. Anarchy, in the realm of documentation, argues that using wiki could bring the documentation closer to the product, but at what price?
The fear of anarchy is a fear from trading proficiency for both accessibility and quality of the text.
A wiki-based documentation system thwarts anarchy with a workflow that allow freedom for the writers, but edit them strictly.
Worse comes to worst, and the wiki-based help website becomes a total mess, the immediate response is to shut it for all writers, but the technical writer in charge. This returns to where we are today.
The Wikipedia case study shows that, fearing of being constantly edited, writers evolve from writing fragments of information into taking a top-down approach. After all, if my text befits the structure of the website, it might be edited, but certainly won’t be thrown away altogether, or even worse, neglected.
The goal is to get accurate documentation that covers the entire product, in a logical structure that makes topics easily found.
This goal will be achieved naturally, through the suggested workflows.
Passive Writer
Active Writer
Dispute over Content
The T.W., or the technical personnel is asked to write on a certain topic.
Text comes in.
The T.W. writes the text.
The text already exists.
The Technical Writer identifies the new text through the Recent Changes mechanism, and a recurrent task (say, “check for changes daily”).
The T.W. edits the new text.
The T.W. places the new text where it belongs.
The text contributor goes over his/her text.
The topic is reviewed by the technical personnel.
T.W. and technical personnel, or technical personnel among themselves don’t agree on the way the text should be written, presented, placed, etc.
They open a discussion in the Conversation’s page.
They discussion attracts contributors and parties, the topic is discussed extensively, and, hopefully, new insights emerge and are covered in the documentation as well.
The topic gets a status of “Version x.xx Compatible”
Action Item 3 Add screenshots from Wikipedia.
בבלוג זה
בכל הבלוגים
