Getting Started With WikiText

We Recommend These Resources

Documentation is the bane of all developers. Nobody likes to write documentation, but most people know we need it. Even more so in Open Source projects. If you don't have a decent documentation, it will be hard to find contributors which will eventually stall the projects ability to acquire new committers.

While documenting code is discussed quite controversial (see here, here, here and here), most people seem at least to agree that a high level documentation outlining the concepts of the software in question is appropriate.

The options to write high-level documentation are:

Word processors like Word, OpenOffice, Pages and the like
LaTeX
DocBook
Wikis

Using word processors for writing high-level documentation has serious drawbacks, especially when a whole team needs to contribute to the documentation. Do you remember master documents?

LaTeX is a great alternative, as it allows us to split documentation across several text files - this allows for efficient team work. Moreover, text files just cannot break and can be versioned / merged / diffed quite easily. However, LaTeX syntax is not for the faint of heart.

DocBook is great, too: it uses XML to describe documents and has a great number of transformations to about every output format you could think of (PDF, HTML, EclipseHelp, HTML Help, JavaHelp and even man pages! However, not everybody likes XML and in fact DocBook tends to be a little noisy.

So this leaves us with Wikis. They are great in many regards: you can write your documentation online, most wikis support versioning and diffing to a certain degree and most wikis have a decent collision detection that helps to work on documentation collaboratively. Thanks to offline Wiki editors for IDEs, we can even store wiki documents in local files.

Enter WikiText

WikiText is such a tool. It actually is very flexible, as it allows you to use a multitude of wiki dialects to write your documentation. It also supports a number of output formats (HTML, Eclipse Help, DITA, DocBook and FOP). What's more, it features a really nice text editor that can display Wiki markup almost in a WYSIWYG fashion. WikiText is developed and maintained by David Green.

So, without further ado, here is a quick introduction on how to install WikiText, writing your first document and transforming it to HTML.

Installing

Make sure you have a recent version of Eclipse installed. Then:

Point your update manager (Help -> Install new software) to the Mylyn Update Site (http://download.eclipse.org/tools/mylyn/update/weekly/e3.4)
Select the most recent version of Mylyn WikiText (as of this writing, this is WikiText 1.1.0.I20090423-1700-e3x) and install

After the obligatory Eclipse restart, you can start using the WikiText editor.

Writing your first document

Create a new project (File -> Project... -> General -> Project
Create a new file. We will be using the Textile wiki syntax, so let's name it HelloWorld.textile

Enter some text:

h1(#id). An HTML first-level heading

Textile syntax is really simple. You can _emphasize_ text or *emphasize it even more*.

Scaled images:
!{width: 50%}images/eiffelturm.jpg!

Enumerations also are very easy:

* An item in a bulleted (unordered) list
* Another item in a bulleted list
** Second Level
** Second Level Items
*** Third level

# An item in an enumerated (ordered) list
# Another item in an enumerated list
## Another level in an enumerated list 

Let's have more headings:

h2. An HTML second-level heading

Here is a table:

|_. Header |_. Header |_. Header |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 1 | Cell 2 | Cell 3 |

h2. An HTML third-level heading

Here is some code:

bc..
package org.eclipse.workflow;

public class Workflow {

}

p. Here is a plain old paragraph. It needs to start with "p." to mark the end of the code block above.

h4. An HTML fourth-level heading

Of course, we can also have hyperlinks: "Peter's homepage":http://www.peterfriese.de 

h5. An HTML fifth-level heading

h6. An HTML sixth-level heading

Create a new subfolder images and place an image in his folder. I used this one.

You can always switch over to the preview pane, but you will notice that the source editor already does a decent job at rendering the text in a kind of WYSIWYG manner:

Transforming your document to HTML

In order to convert your document to a nicely rendered HTML document, just right-click on HelloWorld.textile in the package explorer and select WikiText -> Generate HTML. This will create anew file HelloWorld.html in the same directory. Double-click it to open it with a browser:

Automating, PDF, splitting documents,...

I hope I could whet your appetite. In the next installment, I am going to show you how to automate the process of transforming WikiText documents into output documents, how to create PDF (by way of exploiting DocBook) and how to split your documents into smaller chunks so you can work on them as a team. Stay tuned!

From http://www.peterfriese.de

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Thomas Mueller replied on Fri, 2009/04/24 - 3:05am

Wikis are a pain because they all have a different syntax. I write my documentation in XHTML directly (with a text editor, usually Eclipse). PDF is generated using an OpenOffice macro.

Dominique De Vito replied on Fri, 2009/04/24 - 3:53am

I really, really dislike wiki syntax! I can't imagine me living for learning all these different syntaxes.

I am just thinking about a Java rich client that would enable (for example) :
- to use a rich text editor (providing a subset of HTML capabilities for decent documentation write)
- to download/upload documents from an OSS project web site in order to collaborate.

Pivot includes such richt text editor into its roadmap, and then, while Pivot is Swing 2.0-oriented, it looks like interesting for me.

Dominique
http://www.jroller.com/dmdevito

Peter Friese replied on Fri, 2009/04/24 - 5:44am

Oops - I am really surprised to see that there are such strong reactions against wikis. The good thing about WikiText is that you can choose a Wiki syntax of your liking. WikiText supports Confluence, MediaWiki, Textile, TracWiki and TWiki syntax (see http://wiki.eclipse.org/Mylyn/FAQ#What_wiki_markup_languages_does_WikiText_support.3F). What's more, you can define a parser for your own Wiki dialect if your favorite Wiki is not yet supported.

Prasoon Kumar replied on Fri, 2009/04/24 - 6:15am

Sweet. I will start using this right away in my team. Is it possible to upload wiki files to company wiki automatically? We use moinmoin and Mindtouch. Anxiously waiting for PDF generation from wikitext article.

Mladen Girazovski replied on Fri, 2009/04/24 - 6:26am

I think wikis are great, using DokuWiki myself.

Check out WikiCreole for a wiki markup standard.

Dominique De Vito replied on Fri, 2009/04/24 - 7:27am

What is the added-value of a wiki ?

While one could have a sweet editor like Google Docs, to give one example, what is the added-value of a wiki (and particularly, wiki syntax), for writing the documentation ?

Thanks for answer(s).

Mladen Girazovski replied on Fri, 2009/04/24 - 7:40am

A central place for storing, viewing & editing documentation in a very fast way, including versioning etc. pp., for some wikis there is a lots of plugins extending their functionality.

In a wiki you can search over all the wiki entries for terms etc. in a simple and fast way.

Wiki syntax is supposed to be easy to learn & very fast to use, so in theory the documentation could be up to date :)

For teams it is important to be able to share information, everyone in the team can correct/add articles to the wiki, with a very low overhead.

Haven't used Google Docs myself., so i can't comment on it.

Dominique De Vito replied on Fri, 2009/04/24 - 8:16am in response to: mgira

I think all that a wiki can do, an online word processor could do, or may do, the same.

From wikipedia:
""
Google Docs is a free, Web-based word processor, spreadsheet, presentation, and form application offered by Google. It allows users to create and edit documents online while collaborating in real-time with other users.
[...]
Open documents are automatically saved to prevent data loss, and a revision history is automatically kept. Documents can be tagged and archived for organizational purposes.
[...]
Collaboration between users is also a feature of Google Docs. Documents can be shared, opened, and edited by multiple users at the same time.
""

And if you are not happy with Google docs, here are some lists, as an online word processor may not include all features you want/need:
Comparison of office suites
List of online spreadsheets
List of online word processors

Mladen Girazovski replied on Fri, 2009/04/24 - 8:37am

Then show how would you search all your Online Docs for the occurence of one or more words.

As is said, i have no experience with Google Docs myself, but when i perform and document the installation of a Server (JBoss, Tomcat, MySQL, etc. pp.), it takes me about 10-15% more time than without writing documentation, i can do it simultaneously.

When i tried this with MS Office, the task of documenting would take longer, it used to be real work, so i only did it when there wasn't much else to do..

Apart form that i can link in a wiki, inside the same wiki, or any webpage, again, really fast without much effort, and i can see if the linktarget exists already or is missing.

As i said, wikis are supposed to be easy and fast, formatting is not important, it is the contained information.

So wikis are tools for information management and colaboration, not for creating shiny Docs/Presentations for customers.

Dominique De Vito replied on Fri, 2009/04/24 - 8:45am in response to: mgira

I think all that a wiki can do, an online word processor could do, or may do, the same.
Then show how would you search all your Online Docs for the occurence of one or more words.

Come on, do you see any technical difficulty to stop an online word processor offering that service ? Let's imagine the following: when you save/upload a document, then start the indexing process.

That's not the topic. We are talking about online word processor familly.

Mladen Girazovski replied on Fri, 2009/04/24 - 8:55am

A small manual intervention to be able to use Google Docs, however, this feature (and a few more) are built in to every wiki system, since this was what they were made for.

Actually you are talking about online word processors, this post is about wikis.

Maybe you should give a wiki a go and try out for yourself, online word processors/spreadsheet sure have their value, but they are not made to replace wikis ;)

Dominique De Vito replied on Fri, 2009/04/24 - 9:16am

I am talking about wiki too, about wiki future (versus online word processor).

Why wikis won't be replaced ? What are the wiki key features that won't be replaced ?
I am kind to read/learn.
Thanks

I can give one reason, but there are maybe other ones (and if you have other ones, again, I am kind to read).
Some wikis give the capability to write scripts, and then, to enhance page behavior. However, for main wiki tasks, that is, writing documents, wikis have to fight hard against online word processors, because while using those processors, users have not to learn any syntax. Those processor are more user-friendly, offering a better out-of-the-box experience IMHO.

Mladen Girazovski replied on Fri, 2009/04/24 - 9:57am

I do not use wikis to write "documents", but documentation.

Might sound like the same, but the difference is important here. If you write a document, you choose your layout, create aTOC, maybe a short intro.

When i write documentation, i merely don't care about those things, only a little bit, the TOC is created in DokuWIki for instance without me doing anything except for choosing the right headers. Of course you can do this with a doc template in any word processor,but you writing documents worry way to much about formatting, like page breaks etc.

In a wiki there is no such thing as page breaks, layout is not very important,it doesn't matter how it looks when it's printed (of course there are exceptions).

When you say user-friendly, it is important to understand who your users will be.

It won't be the avarage secretary/managers writing letters or documents, it will be developers/administrators.

For the latter it is much faster to use some really simple markup instead of providing buttons and WYSIWY. A developer won't have much trouble to learn a handfull of wiki markup expressions.

For instance, in dokuwiki if i want to format a paragraph as a commandline, all i need to do is to insert 2 spaces in front of the line, no need to select another Font, Size or other style manually with the mouse. Same goes for bold text, etc. Think of it as an DSL for documentation from developers for developers , only a small subset of formatting is possible, but that is all that is nessecary.

This makes writing documentation really fast, and that is user friendly to me as a developer, since i do not need to delay other work for the sake of beeing able to communicate how & what i have done, ie.setup of an IDE, or building a SW project. As i said, when it comes to documenting installations etc. i can do it simultaneously, and we all know that if it's not done immediatly, it won't be done for a long time, if even at all.

btw., "wiki" originally meant fast :)

That is one of the main point of wikis.

The indexing is built in in wikis, all your pages/articles in a wiki can be threated as one doc if it comes to searching, you use linking a lot in wikis (for references).

All in all i think we are comparing apples to oranges when we compare (online) word processors to wikis, they are not meant to replace each other, in fact you can combine them really nice (linking), so you can get the best of both worlds.

IMHO

Philippe Lhoste replied on Fri, 2009/04/24 - 10:57am

Interesting article and discussion.

Thomas: "Wikis are a pain because they all have a different syntax." - Well, the point here is to choose a syntax and stick with it. It is not about writing in several different wikis across the Web, but doing your own doc. Same answer to Dominique De Vito's initial remark.

Thomas: "I write my documentation in XHTML directly" - I can do that for small blog entries, but it can be a pain for lot of documentation pages, that's not the most friendly markup language I know.

Wiki syntax vs. online word processors: online WP are... well, online. With wiki syntax, you can write your doc in your plain text editor, in a place where Internet isn't available (the proverbial plane or some remote province), you don't rely on a service which can be out or even can disappear someday, because the company is bankrupted or just think they don't earn enough money out of it.

Most wiki syntaxes, particularly Textile or Markdown, are made to ressemble closely of free text you just type on your editor. So they aren't so hard to learn and are quick to type (unlike XML).

Another advantage: if you write plain text files, you can easily put them in VCS, which is harder to do with online tools...

Now, to each his own, of course...

Dominique De Vito replied on Fri, 2009/04/24 - 11:01am

Well, some word processors are lighter than other ones.

One lighter "word processor" is the richt text editor embeeded into gmail. Is it light enough for you ? For writing documentation ?

As you talk about document versus documentation, I have found an interesting idea.

You say wiki (with special syntax) are nice enough to write rapidly documentation. OK, well, IMHO emails look like documentation, or are documentation-like (as emails are often rapidly written with less care about the text structure); so, why wiki syntax is not used for writing emails ?

Well, I can't imagine an email client proposing to write emails with wiki syntax, while saying that such syntax is better as emails are not documents, but more like documentation (with less care about the structure), and such doucments need to write rapidly (then, the wiki syntax).

Rich text editor, IMHO light word processors, are quite much more popular than wiki. They are more mainstream (think about those rich text editors used for writing emails). I have some doubts about wiki (with its special syntax) future when I see how much such rich text editors are popular/mainstream and raise, with more and more collaboration features.

Dominique De Vito replied on Fri, 2009/04/24 - 11:12am in response to: philho

Come one, offline/online barrier/separation is going to disappear with on-coming browser enhancements.

When you use a rich text editor, the underlined format is XHTML, and in the end, text files. You can place them also into CVS. Remember, Google Docs, for example, provides a revision tool.

David Green replied on Fri, 2009/04/24 - 11:16am in response to: prasoonk

Great article Peter. I really like how you start off with motivation for using wiki format.

@prasoonk though it may not be as eloquent as Peter's article, you can find out more about WikiText generating PDF here and from the WikiText User Guide.

For all of the wiki skeptics, there are some compelling benefits to using wiki formatting, be it in files or in a wiki: It's plain-text, which makes it very easy to collaborate (either via wiki or source repository such as CVS, GIT, SVN, etc.); Wiki markup is compact and non-obtrusive -- so when you look at your document you see the content, not the markup; A low tooling bar to contributing -- you can do it using your web browser, vi, notepad, etc.

Thanks again Peter for the great article.

mark taylor replied on Fri, 2009/04/24 - 9:14pm

FCKEditor is a rich text I've integrated into applications before (is the editor at the bottome of this page FCKEditor? It's a bit slower than the version I've used). FCKEditor is trivial to integrate; output is xhtml which is trivial to work with; stores in a db just like plain text.

IMO, there's not excuse/need for wiki markup today besides preference.

Mark Thornton replied on Sat, 2009/04/25 - 5:45am in response to: mtaylor

There are wiki's which support wysiwyg editing. However the major feature of wiki's over text editors is the linking between 'pages'. Wiki's make this really easy.

Bernd Eckenfels replied on Sat, 2009/04/25 - 6:35pm

We are using Daisy (Coccoon based) DMS for writing product documentation. This comes with a Wiki for text entry (including a Rich Text Editor) and allows multiple output formats (es well as support for translation and branching).

Personally I like the RAW mode of Wikis, but we have a lot users who prefer the WYSIWG editor. Both are satisfied with this solution.

On the Intranet we use TWiki and it also offers both editor modes. If the Wiki Plugin for Eclipse wants to be accepted as a productivity tool, it has to have support for this, too.

Bernd

manuel martinez replied on Wed, 2009/04/29 - 11:34am

Hi, I´ve just started using WikiText and I really like it. However I found a problem trying to set styles to tables. If I select "Generate HTML" I get my html page with the styles I set, but if I select "Generate Docbook" I get an XML file where tables have no styles, and if I generate a html using Docbook I can not set borders and stuff like that. Is there any way to solve this? Thanks in advance.

emil gigi replied on Tue, 2009/06/02 - 4:03am

burs burslar replied on Sun, 2009/06/28 - 5:26am

Thank you for this informative read, I really appreciate sharing this great post. Keep up your work.
burs

sbs sonuçları

nedir

Ed Sutton replied on Fri, 2010/01/22 - 1:31pm

Using a text editor to create HTML or XHTML is silly; for perfections and masochists and not for me. For creating document pages I would much prefer to use a Wiki syntax and WikiText sounds like a great idea.

I use Doxygen to create HTML user documentation for my Linux C++ API's and applicatiuons. This works great for documenting code but for other pages such as user-manual-sections and quick-start sections, not-so-much. While not WYSIWYG, iI think WikiText could be a solution for me if I can crate the content in wiki format, export to HTML, and integrate with the Doxygen make in my build process.

Thank you for a great article!

-Ed of the Mountain

Mike Forris replied on Wed, 2010/04/07 - 8:21am

Watch sinful comics here: http://bit.ly/dvVpBn