TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Pow to the people with a Wiki From:hedley_finger -at- myob -dot- com -dot- au To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 20 Dec 2002 10:19:58 +1100
Open letter to Free Framers, especially Jeremy Griffith, Bill Swallow, and
Dennis Hays:
Is it time to rethink the idea of a online periodical, the mailing list,
and the Web site?
What about a Wiki? Don't know what a Wiki is? Think of online help
published on the Web that allows ANYBODY to:
@ It's a democracy: anyone can contribute new material or revise material
they know to be inaccurate, or unclear, or in violation of style guides.
The site grows organically to reflect the interests and needs of
participants. This is in contrast to readers of your typical Web site, who
are totally at the mercy of whatever malign or benevolent dictator acts as
WebMaster.
@ You can embed easily-learned symbols to specify heading level, apply
emphasis, include lists (both numbered and bulleted), and build tables
WITHOUT having to learn or use clumsy HTML tags, and much more.
@ You can quickly embed links to other topics by a clever topic-naming
scheme that allows the Wiki engine to build the HTML links in the displayed
page. You don't have to find the specific URL yourself. (You can also
embed URLs external to the Wiki.)
@ You can embed links to topics that OUGHT to be written but for which you
have no time. Another contributor can click on the placeholder link to add
that topic.
@ Versions of topics are maintained with the ID of whoever created or
revised a version. You can compare versions to see what was changed.
@ You can view recent additions and changes by date on a special page. So
you can just drop in every few days or weeks and check out new or revised
topics that interest you.
@ You can find all the pages that link to a particular page (wouldn't it be
nice if help development environments did this?).
@ You can find topics by Boolean search or by walking a hierarchical or
nested table of Contents.
@ The Wiki engine handles potential editing collisions by warning if you
try to revise a page already open for revision by someone else.
@ Contributors are identified; usually, you can go to a bio page to find
out more about their wares ... ooops! them and the work they do, and
perhaps see a picture of the curmudgeon that's been contributing to the
list for years.
@ The Wiki admin can protect some pages absolutely, good for the home page
and the navigation panel at the left side. Other pages can be selectively
protected, so that only authorised contributors can access them.
@ You can build templates for different kinds of pages. For example, one
might allow any content to be revised. Others might allow contributors to
only append comments to the foot of a page, good for a rudimentary issue
tracking system.
*** What's bad about a Wiki ***
@ Some sites are totally open to anybody, which means that sooner or later
(usually sooner), morons post textual and pictorial pornography, or just
trash pages, or tag pages like kids with spray paint. Easily fixed with a
registration and login scheme that irrevocably identifies contributors.
@ Some Wiki implementations were designed by left-brained serial thinkers
(far worse than serial killers) who believe that text is king. These sites
don't allow graphics in case someone posts a rude picture (but you can
still post rude words; hmmmm).
@ Some Wikis are impenetrable. Like a jungle, you know there are some
juicy fruit in there somewhere but there are NO signposts to follow.
Instead, you click madly on a trail of links hoping to stumble across
something tasty in the undergrowth.
@ Tables of Contents are usually just another topic. This means that it
cannot be viewed at the same time as the topic, perhaps in a lefthand
navigation pane, as you can with online help. It also has to be manually
maintained: contributors have to remember to add the title of a new topic
to the contents topic, to change the wording of a link when the topic title
changes, and to delete the link when the page is removed. As we all know,
manual maintenance allows creeping structural entropy. (Did you like that
purple phrase I just invented? I like it so much I'm going to say it
again: 'creeping structural entropy'.)
@ Index. What index? It sure would be nice if someone would implement a
Wiki that allowed the contributor to: create new entries and subentries, or
add subentries to existing entries. You would need some way of viewing the
existing index while embedding entries in your topic, to avoid index
terminological anarchy. (Did you like that purple phrase ...?)
*** Where can I Wiki? ***
By now you are undoubtedly in a sopping lather of expectation and yearning,
and want to know more. Go have a cold shower, then look up:
(Links courtesy of Opera bookmarks file, massaged with regular expressions
in TextPad.)
*** Where to from here? ***
Surely there are some PHP, Perl, or Python geeks on this list who know a
good idea when they see it. Unfortunately, your humble correspondent does
not have the programming skills to participate in the construction of a
Framers Wiki. But I could work on the design and testing.
Over to you, constant readers,
Hedley
--
Subscribe to Free Framers -- send this message
subscribe framers your -at- email -dot- address
help
end
to <mailto:majordomo -at- omsys -dot- com?Subject=Subscribe%20Free%20Framers>
Hedley Finger
Adobe Certified Expert, FrameMaker 5.5.x
Technical Communications/Best Practice Mentor
MYOB Australia Pty Ltd <http://www.myob.com.au>
P.O. box 371 Blackburn VIC 3130 Australia
12 Wesley Court Tally Ho Business Park East Burwood 3151 Australia
Tel. +61 3 9222 9992 x 7421 Fax. +61 3 9222 9880 Mob. +61 412 461 558
<mailto:hedley_finger AT myob.com.au>
(C) MYOB Technology Pty Ltd
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
