Writing a Book, the Wiki Way
Update for August, 2010. I have "published" my second wiki reference book for Tiki Wiki CMS, Tiki Essentials. See http://tikiwiki.org/blogpost400 for the announcement.


This article is under development.

or....

How I did it. The story behind TikiWiki for Dummies Smarties.




Introduction

This article explores the evolution of TikiWiki for Dummies Smarties: A beginner's guide to TikiWiki. I'll talk about why I started the project, how I created the "book", and where it is headed.

If you haven't seen the book, I encourage you to take quick look right now. It's only a link away.

If you're new to TikiWiki, start here.


Why Write for Free?

My first exposure to TikiWiki (Tiki) was in early 2005. Bill Albing, Sherry Steward, and I formed KeyContent.org and started looking for a content management system (CMS) that would could power the website and give us all the "goodies" we wanted (wikis, blogs, forums, and so on).

After exploring the hundreds of different applications available, we settled on Tiki primarily due to its overwhelming feature set. It could do everything (and anything) we wanted. The next step was to install Tiki and start playing with it.

The mooch

mooch (mooch)
n. One who tries to get something free of charge; a sponge
v. To get or take without paying, or at another's expense


Although TW had many features, it seemed (to me, anyway) that usability, especially for new Tiki administrators, was not one of Tiki's key features.

Almost immediately I started asking questions to the TikiWiki community. Lots and lots of questions. And In fact, if you review the TikiWiki forum archives, you'll see that sometimes I asked 2, 3, or more questions in a single day.

Some of the responses directed me to the TW documentation (which was starting to undergo a complete redesign), but most of the responses were directly from other Tiki developers and admins.

The giver

Eventually, I got the hang of things and began to make the most of Tiki's features. We heavily customized Tiki for KeyContent.org — tweaking it to be exactly what we wanted.

Soon, I became a Tiki-evangelist and started using Tiki for other web projects. In time, I even became a code contributor — working directly with the TikiWiki source code in CVS(and later SVN). At first my check-ins were quite trivial (a reworded error message here, a new icon added there). But before too long, I was reworking the PHP code, adding enchantments, and generally becoming a "key contact" in the TikiWiki community.

My coding skills are... well... honestly, not very good. So I looked for other ways to contribute.
  • I contributed to the official documentation site, eventually becoming a member of the editorial board
  • I became involved in reworking Tiki's base UI -- with a focus on usability for new admins.
  • I joined the Tiki promo squad to help spread the word and improve Tiki's public image.
  • I became a forum monitor, checking the site on a daily basis to help new Tiki admins.
After a few months of "forum duty" I came to a realization — the Tiki documentation, although very comprehensive, was missing a key reader: The new Tiki admin who wants to get up and running.

I thought of a few ideas (creating a walk-through, a set of tutorials, an evaluator's guide) but was not able to follow through on any of those ideas.

Eventually it hit me — why not write a book?

After all...
Those that can, do. Those that can't, write about it. :-)



How to create a wiki book







Paper is dead....

TikiWiki is a very active community project. By some accounts, there's a code commit every 2 hours. This means that things are continually evolving and improving.

And since Smarties was a wiki, it was quite easy to keep the guide in sync with the software. However, this meant it become exceedingly difficult to pick a point when the project could be seen as "done" and I could create a printed version. As soon as I clicked "OK" for the printed version, it was already out-of-date.

In my mind, the whole idea of a "printed version" of a wiki project seemed counter-intuitive. One of the main features of wikis is that its a snap to update and change!

At that point I abandoned the the idea of a printed, hardcopy version of Smarties. Readers could print any page of the wiki, whatever they were reading. No one really wanted a book. Or did they...


Or is it?

One piece of feedback that I routinely received, is similar to this one:
Your guide is great. But is there a way for me to print the entire book at once?

It slowly become obvious to me that print is not dead... it just needs to available on-the-fly.

Tiki's multiprint feature (after a few tweaks, which made their way back to the core code base) fulfilled this requirement perfectly. With it, users could select any (or all) of the wiki pages, and create a "printer-pretty" version of the guide.


Enticing contributors



  • I send out semi-regular newsletters to the contributors


Around the world

As soon as I began review the site statistics, I quickly saw that nearly two-thirds of my readers came from outside the United States.

With the help of the many, talented translators, Smarties is now available, in various levels of "completeness", in Spanish, German, Portuguese, and Japanese.


My desire to make Smarties multilingual has led to my involvement with http://www.wiki-translation.com — an effort to improve the "translational" ability of wikis.


What's next?





Awards and Reviews

TikiWiki for Dummies Smarties received a Merit Award from the STC Carolina Chapter Online Competition. This provided a great opportunity to have the project reveiwed. I've included a snapshot of the judges' scores (out of possible 5) and comments:

1. Does the entry fulfill its purpose? (Scores: 4-4-4)

Items for improvement:
  • Is it easy to find specific information? (2x)
  • Do the overviews or introductions effectively orient users and provide context?
  • Does the entry provide clear and sufficient instructions for how to complete tasks?
  • Did the author(s) make appropriate choices for:
    • Site design: Are elements such as web pages, forms, photos presented in a well integrated manner?
    • Context sensitivity(2x)
    • Language (2x)

2. Is the content of high quality and is it communicated effectively? (Scores: 4-4-3)

Items for improvement:
  • Is the information well written?
  • Are procedures (if used) presented in clear sequential steps?
  • Do all of the navigational elements, such as hyperlinks, resolve correctly?
  • Is the interface easy to use?

3. Is the content well integrated and organized? (Scores: 3-5-4)

Items for improvement:
  • Is the table of contents or navigational equivalent complete and comprehensive?
  • If there is a full text search capability, is it easy to use?
  • If there is a full text search capability, does it support wildcards, case sensitivity, and word variation? (3x)
  • If there is a full text search capability, can you specify a search area? (2x)

4. Are the communication media used effectively and appropriately? (Scores: 4-4-4)

Items for improvement:
  • Does the design minimize the need to scroll where possible?
  • Are the graphics attractive and of high quality?
  • Are media elements (such as sound, video, animation, etc.) of high quality?
  • Is the design appealing and inviting?
  • Are the screens easy to read?
  • Are graphics used effectively to communicate concepts?


Selected Judges Comments

Section 1

I really like this entry, especially the name. ... I very much like that this reference guide makes it very clear that seeking information and help is something that “Smarties” do!
These Overviews and introductions seem inconsistent.... some pages had an “IN THIS SECTION” area at the bottom of the page, where others had the “IN THIS SECTION” area at the top of the page.
Consider adopting a writing strategy that will make it easier to support globalization.
The layout of the content itself is good ... but there are some issues with design and style that could be improved upon to take this work to the next level.
Consider streamlining design elements for a less busy look...
There is a great deal of very helpful information presented in this Wiki format.

Section 2

There are a lot of typos.
Try to be more consistent about how you structure the task information.
Writing style is playful ... while providing a great deal of helpful information.
...consider re-reading and perhaps removing some of the colloquial language.
There are minor typos throughout...
Proofreading the entire document would really make a big difference.

Section 3

There are a lot of topics that are not included in the table of contents...
The order of areas in the table of contents does not match that in left-hand Contents menu.
I found the search function challenging to use.
The Related Topics drop-down on each informational page is useful and well placed.
Wiki-based organization lends itself to intuitive use by those familiar with Wiki-source information.

Section 4

I found the screen shots to be low in quality.
I also liked the icons that you used for Warning, Note, and Tip.
Why have figure captions for screen shots?
When I watched the video ... I also was distracted by repeated typos.
Consider perhaps less imitation and a cleaner/less cluttered GUI.
Sound would be nice to go along with the text of the videos...
Since some of the pages are busy with graphics, it would be nice to have the option to view the pages as text only
There are a number of other layout issues.... I’d recommend increasing white space by getting rid of unnecessary style choices... and to increase spacing between lines.


Discussion

I was very pleased with the overall score and award. The judges' comments were especially insightful. In my opinion, there are really three categories that I will try to address in future updates of Smarties.

Typos and Proofreading

I think this is where Smarties lost the most points. In a wiki-based project, it is so easy to "publish" information immediately, I sometimes miss the step of "getting it correct." I have received a few comments from readers, pointing to typos and other errors. I would love to have more contributors and authors involved in writing and editing.... many hands (or eyes in this case) make for light work.

The default search functionality in TikiWiki is a known deficiency, and was identified by all three judges as an item that needs improvement. This is especially important, considering that nearly 15% of all visitors to Smarties use the site search.

I've attempted to "bridge" this problem by:
  • Adding a list of common search terms (with direct links) on the Search Results page.
  • Adding a Google Custom Search Engine option, after the initial search.

Table of Contents and Structure Consistency





Become a Smarty today!



Contributors to this page: Rick Sapir and marclaporte .
Page last modified on Monday, August 02, 2010 08:13:05 am EDT by Rick Sapir.

Key Pick New

Bill Albing has some suggestions to improve STC competitions. Read and let us know, what do you think?

Other Key Picks... Read more

About KeyContent

About KeyContent
KeyContent.org is an idea space where you can express your insights about your profession. Think of this site as a white board with a brain. You create and edit articles or portals to other sites and share your insights... Read More


Key Ads

Key Connections

Join KeyContent on these networks:



Key Products

Make Custom Gifts at CafePress

Key Promotions