tag:computers.tutsplus.com,2005:/categories/trac Envato Tuts+ Computer Skills - Trac 2014-03-10T06:06:02Z tag:computers.tutsplus.com,2005:PostPresenter/cms-19772 How to Build Your Own Wiki <p>Now that you understand <a href="https://computers.tutsplus.com/tutorials/what-are-wikis-and-why-should-you-use-them--cms-19540" target="_self">what wikis are all about</a>, and how they can be used in your business, all that's left is to start your own wiki and get your team using it to organize your info.</p> <p>It sure would be great if I could point you to a single website where <em>the</em> "Wiki" lived. But wikis actually come in a lot of flavors. The constants are still the same: they're all designed to let you easily collaboratively create content, and easily link to anything with simple referencing, but they each have their own strong points.</p><p>In this tutorial, I'll show you the best tools for building your own wiki, and then teach you how to start, edit, and grow your wiki.</p> <h2>The Very Best Tools to Build a Wiki</h2><p>Before you start building your wiki, you'll need to decide what you want to power your wiki. Just like you could build a website with plain HTML, a full-featured CMS like WordPress, a simpler CMS like the new <a href="https://webdesign.tutsplus.com/software-and-tools/ghost" target="_self">Ghost</a>, or anything in-between, you can use a ton of different tools to power your wiki.</p> <p>First, here's the 3 best tools just for making a wiki. If all you want is a simple, straight-forward wiki, these are for you. Then, we'll look at some of the other popular tools that let you make a wiki, and also have extra features.</p> <h3><a href="http://www.mediawiki.org/">MediaWiki</a></h3> <p>Let's look at the big guy first: MediaWiki. This impressive wiki engine is what powers Wikipedia, and most other wikis you've likely seen before. If you want to use the same tools as most popular wikis online, MediaWiki for you.</p> <p>But there's something to keep in mind here: <em>MediaWiki powers Wikipedia</em>. I know, I said that already. But think for a second about what that means. Wikipedia is tremendously large, edited by millions of different users. So by extension, MediaWiki is designed with a lot of features geared towards a tremendously large wiki being edited by millions of users. If you don't think you or your small business needs all that, then maybe one of the simpler wikis on the list would satisfy your needs better.</p> <p>That being said, MediaWiki does the job very well. It's widely supported thanks to its popularity, <a href="http://www.mediawiki.org/wiki/Installation" target="_self">relatively easy to install</a>, and—considering it powers Wikipedia—is sure to be around for a long time. It's the WordPress of wiki engines.</p> <h3><a>dokuwiki</a></h3> <p>Dokuwiki strikes me as the best example of a wiki with all the essentials you want without anything you don't really need. It doesn't use a database to store your wiki content, making it a bit simpler to install, backup, and manage than your average wiki. But don't be fooled into thinking Dokuwiki isn't a full-featured piece of wiki software. It has an elegant and simple text formatting syntax, offers access controls and authentication, and even has a plugin community.</p> <p>If you want something simpler than MediaWiki—and that's easier to backup than MediaWiki since it works without a database—Dokuwiki's definitely worth checking out.</p> <h3><a>Roadkill</a></h3> <p>Roadkill deserves special mention here as it's the only .NET powered wiki in the list. If your company uses Windows Server internally, then Roadkill might be your simplest choice on this list. It runs on a modern stack of web technologies, and is powered by the .NET framework. Whereas MediaWiki and dokuwiki are intended to run on the <a href="https://en.wikipedia.org/wiki/LAMP_(software_bundle)" target="_self">LAMP stack</a>, Roadkill will be simple to get running on your Windows Server, and it still includes the modern features you'd  Anything to make the process of setting up your wiki quicker and easier, right?</p> <h2>It's a Wiki and Then Some</h2> <p>You'll likely want to use MediaWiki, dokuwiki, or Roadkill, but they're not the only ways to make a wiki. Here's a quick list of some of the most exciting other wiki tools that offer extra features. If you've already decided to go with one of the above tools, though, you can just skip ahead to the Wiki walkthrough.</p><i> </i><h3><a>Trac</a></h3> <p>Trac is everything you could want from a wiki if you're using one to document your software. Essentially, take a version control tool like Github, combine it with issue tracking and a wiki for documentation, and you have Trac.</p><p>If you're developing software, or anything else where you need to track bugs, then Trac could be a <em>great</em> wiki solution for you. It combines issue tracking and version control software with a wiki. You can inspect your code, track bugs, and document the whole process in one place. If your business involves coding, it's hard to get better than Trac.</p> <h3><a>Redmine</a></h3> <p>Take everything that's great about Trac, and add project management, and you've got Redmine. It's a wiki, version control, bug tracker, and everything you'd expect from a project manager—Gantt charts, calendars, forums, time tracking, and more—all in one.</p><p>It's impressive, but it also might be too much for your needs—or it might be the one app to bring everything in your business together.</p> <h3><a>XWiki</a></h3> <p>XWiki bills itself as a "<a href="http://platform.xwiki.org/xwiki/bin/view/Main/SecondGenerationWiki">second generation wiki</a>," since it uses the principles of wiki design to build collaborative web <i>apps</i> instead of just web pages. There's a lot you could accomplish with it—enough for an entire separate tutorial—but for now I'll leave you with <a href="http://enterprise.xwiki.org/xwiki/bin/view/GettingStarted/WebHome">their Getting Started guide</a>. At the very least, if you like the ideas behind a wiki but want to make more than just a plain site, Xwiki is worth checking out.</p> <h3>That's Far from All</h3> <p>This is by no means a comprehensive list of wiki tools. In fact, there's so many, you could spend hours wading through just the over 140 most popular ones at <a href="http://www.wikimatrix.org/">WikiMatrix</a>. But the tools listed here are plenty to get started.</p><p>You'll most likely want to go with MediaWiki, but otherwise, we've just looked at wikis for Windows Server, ones that will track your bugs and help manage your projects, and let you build apps.</p><p>Now, it's time to put it all together and start using a wiki.</p> <h2>Building and Using a Wiki</h2><p>Wikis can be a bit intimidating. They don't exactly look like Microsoft Word, or Facebook, or really anything else you've used before. Even if you've used Wikipedia, editing and effectively using a wiki in your business is a different matter entirely.</p><p>So let's walk through the basics of using a wiki. You'll see that it isn't a dark, scary jungle at all; it's a calm and pleasant little garden.</p><p>First, you'll need to get your wiki running. That shouldn't be too difficult if you have a hosting account, as most hosting services have a one-click installer (like Softaculous) to get MediaWiki and most of the other wikis we've mentioned up and running. Then, it's time to put your wiki to use.</p><p>I've used MediaWiki in this tutorial because it's the most common. The tasks we're going to go through are basic, and the way you do them in other wikis is often very similar to what's described here. Let's get started.</p> <h3>Reading a Wiki Page</h3> <p>You might think it sounds crazy to be covering something as simple as <em>reading</em> a wiki page. But, to be fair, a wiki is a bit different than your average web page. There are some important things you'll find consistently on every wiki page. Here's an example, with the important areas outlined below:</p><figure class="post_image"><img alt="The parts of a wiki page" data-src="https://cms-assets.tutsplus.com/uploads/users/26/posts/19772/image/mediawiki-reading-wiki.png"><figcaption>The important parts of a wiki page</figcaption></figure> <p><strong>1. Header Image/Logo:</strong> If you ever feel lost while reading your wiki, remember that a simple click on the logo here will send you right back to the first page of the wiki—just like in most sites.</p> <p><strong>2. Top Navigation:</strong> The main navigation is at the top. It's important to look all the way over on the right because that's where the "Edit" and "View history" buttons are, which we'll talk more about later. You'll also find a standard search box, which is the best way to find info not linked in the current page.</p> <p><strong>3. Side Navigation:</strong> This is supplementary navigation, to help you quickly jump to important pages within the wiki. MediaWiki, for example, has links to the main pages in the wiki, as well as a section in its side navigation containing what it calls "<a href="http://www.mediawiki.org/wiki/Special:SpecialPages#Page_tools">Tools</a>," which are links that contain extra info about the page in question.</p> <p><strong>4. Article Title:</strong> This is, perhaps, the most self-explanatory part of the wiki page, and is exactly what it sounds like.</p> <p><strong>5. Table of Contents:</strong> This is a useful tool, especially for long documents with lots of sections. The table of contents is automatically generated, using the heading levels in the page to build an outline of its content.</p><p>That's not so much different from the average webpage, but you'll notice there's a stronger emphasis on links with extra information and simple navigation throughout the page. These are some of the ways that wikis are better at organizing info than a standard webpage.</p> <h3>Editing a Wiki Page</h3> <p>Reading a wiki is simple, and finding your way around a wiki is even simpler than on a standard webpage thanks to its extra links, automatically generated table of contents, and more. Now it's time to edit a wiki page. Here's how a standard wiki editing page looks:</p><figure class="post_image"><img alt="MediaWiki editor view" data-src="https://cms-assets.tutsplus.com/uploads/users/26/posts/19772/image/mediawiki-edit-page.png"><figcaption>Editing a MediaWiki page—here, inside Wikipedia</figcaption></figure> <p>This may seem like a lot to understand, but don't be overwhelmed. To edit the page, just start typing in the box. That's it. At it's most basic, a wiki page is just plain text.</p> <p>Formatting what you type does complicate things a bit, but not much. There are two different approaches you can take towards formatting a wiki page. For every wiki there's some sort of simple style syntax you can use to markup your wiki page. Look at the image above. Can you make out the subheading "Birding, birdwatching, and twitching"? If you look closely you'll see that the phrase is wrapped in "==". This means that phrase will become a level 1 heading.</p><p>There's similar text-based syntax to add every type of formatting you'll see in a wiki page. MediaWiki has a nice page documenting all the <a href="http://meta.wikimedia.org/wiki/Wiki_text_formatting_help">various ways to style content</a>, and you'll find similar documentation for other wiki engines. What's great about the basic wiki syntax is that it's easy to type without leaving your keyboard, and works from any device.</p> <p>If that's too overwhelming, though, most wikis also come with a WYSIWYG editor (WYSIWYG stands for "What You See Is What You Get"), which looks like a mini version of Word or other word processors you're already used to. This helps to simplify the editing process even further, and makes it no more difficult than editing a normal document. If your wiki has a WYSIWYG editing feature, feel free to use it. And more importantly, tell your employees about it. It will help them fear editing a wiki page even less.</p> <h3>Linking Between Wiki Pages</h3> <p>In our last article there was a lot of talk about the importance of linking, how it helps a wiki grow and mature, and gives it so much of its power and usefulness. So, how do we create a link?</p> <p><code>[[My Link]]</code></p> <p>That's it. Seriously. With two square brackets you just created a link to the page "My Link" on your wiki. You could write "Cucumber" instead, to link to your page about cucumbers, or whatever you'd like. You don't have to type in a URL to the page, but only have to type the title of the page inside square brackets. Or, if you want, you can spice that link up a bit:</p> <p><code>[[My Link | some custom text]]</code></p> <p>Now you have a link that, instead of appearing on the page as "My Link", appears as "some custom text" but is linked to the page "My Link." Isn't that simple? That's the absolute best feature of wikis: it's insanely simple to create links. And remember, you can also link to content that's not there yet. You can make the "My Link" link, even if your "My Link" page hasn't been created yet, and the wiki will automatically link to that page when it's been created.</p> <h3>Time-Traveling with Wiki Pages</h3> <p>No you didn't read that wrong. I said <em>time-traveling</em>. What am I talking about? Well, most wikis today have a <em>revision history</em> for each wiki page. It tracks every change ever made to a wiki page, listing who made the change, when they made it, and in most cases a small description of what the change was.</p><figure class="post_image"><img alt="MediaWiki article revision history" data-src="https://cms-assets.tutsplus.com/uploads/users/26/posts/19772/image/mediawiki-revision-history.png"><figcaption>See everything that's ever been changed in a wiki page</figcaption></figure> <p>What's even better is that you can compare the changes made in two different revisions. Check out the image below:</p><figure class="post_image"><img alt="Comparing revisions in MediaWiki" data-src="https://cms-assets.tutsplus.com/uploads/users/26/posts/19772/image/mediawiki-diffs.png"><figcaption>Looking at the differences between two revisions of a wiki page</figcaption></figure> <p>Here we see two different versions of the "Birdwatching" page from Wikipedia. The line that's been changed is highlighted: yellow on the left represents the older version, while blue on the right represents the newer version. In this case the change was minor, just some adjusted punctuation. But think about the power of this.</p> <p>Contained within your wiki is a time machine! Every change, made to every page, over the entire life of your wiki is accessible to you. You can move backwards or forwards, looking at how a page has grown and changed over time. </p> <p>The revision feature found in most wikis is not something to be overlooked. It's your guarantee that your team's data will never be lost.</p> <h1>Keeping Your Wiki Useful and Productive</h1> <p>Well now you have a brand new wiki. Congratulations! Having a wiki though is just the beginning. Think of your wiki like a garden. You've done a lot of work to get it to this point, and now you've just got to get started adding content and getting your wiki adopted by your team members.</p><p>The only problem is, it's easy for your content to get out of hand, outdated, and harder to fix. Or—worse—your wiki can easily get neglected and forgotten. So here's some tips to keep your wiki from stagnating.</p> <h3>Have a Wiki Organization Plan</h3> <p>By this point, you should have in your mind what you want from your wiki. Get those ideas down in writing, make it the first content on your wiki, and highlight it on the Front Page. If you don't explain to your team members what the purpose of the wiki is, what your goals for it are, then your wiki won't become useful. They can't read your mind. And they're sure to appreciate some guidance and direction when it comes to using this new tool.</p> <p>Now, work from that general idea, and stick to it. And make as much content as you need, adding links everywhere that makes sense. It'll grow from there, with the organization you want.</p> <h3>Teach Everyone How to Use the Wiki</h3> <p>This might sound too obvious to need mentioned, but exciting new tools often end up being neglected and overlooked because people simply don't know how to use them. If everyone only sees the wiki as a place to look up info, it'll never grow. So make sure everyone knows how to use <i>and</i> edit the wiki.</p><p>Everyone has stuff to contribute, and the wiki empowers them to do so. You've just got to make sure they know that.</p> <h3>Regularly Review Changes</h3> <p>Most wikis make this really easy to do, by calling out the recently changed pages in some notable way, maybe on the Front page or a Recent Changes page. This gives you a chance to see how your wiki is growing, and what's changed in it recently. That'll help you keep up with your team, stay informed on new stuff, and make sure the wiki itself is working well for your team at the same time.</p> <h3>Incorporate the Wiki into Your Workflows</h3> <p>Want to get the most out of your wiki? Use it. Rely on it for your documentation, for keeping up with that info you'd otherwise have to Google, for anything you'd want to write down or share with your team. Make it the one place for all of your writing, and everyone will learn to make it the first place they'll check. It'll grow on its own from there.</p> <h1>In Conclusion</h1> <p>That should be everything you need to get a successful wiki up and running, and get the most out of it for your team. Wikis are simple but powerful pieces of software. And while there are a lot of options to choose from, I hope you've found one that'll fit you and your small business the best.</p> <p>If you've started using a wiki, we'd love to hear how you're putting it to use in the comments below!</p> 2014-03-10T06:06:02.706Z 2014-03-10T06:06:02.706Z Zach LeBar