Click HERE to order online
Table of Contents
Updates, FAQs & Errata
HERE to order online
by Whil Hentzen
Length: @250 pages
Formats Available: Printed (incl. ebook) or Ebook only
Printed book format: 7"x9" paperback
Ebook format: PDF (8 MB)
Price ($US): 34.95 (printed+ebook) $29.95 (ebook only)
Weight: 2.0 lbs.
Press date: April, 2012
Printed book availability: TK
Ebook availability: TK
Source code: TK
Software is not developed alone. At the very least, you've got users that you'll want to show the goods off to.
And you may have testers, co-developers, sub-contractors, bosses, venture capitalists, and maybe a screenwriter or two
in Hollywood that you'll want on board as well. OK, maybe not that last one.
And they're all likely not gathered in your office all day long. So how do you collaborate with all of these folks?
Enter the wiki.
A wiki is a program that resides on a Web site which allows visitors to edit the pages. Changes made to the pages are tracked through a version control system where users can see what older versions of the pages looked like and who made the changes. It's a wonderful tool for collaborating on the creation of documents as well as an excellent repository for knowledge acquired by a group of people. The Wikipedia, www.wikipedia.org, is probably the most well-known wiki.
And it's one of those tools that, once you include it in your software developer tooklkit, you'll wonder
how you ever got along without it. I've searched long and hard for a wiki that
met my needs as an independent software developer, and DokuWiki is my choice.
This book is roughly broken into three sections. The first is the technical instruction - how to use DokuWiki - getting a basic wiki up and running on a live Web server. Not a lot of frills - the basics plus some essential add-ons.
First, we'll install DW on a local machine (as opposed to a production server or a third-party host), and discuss the various installation options in detail. Then we'll get into building some pages in the wiki, showing you how to edit and format pages, and how to organize a wiki, with a nod given to our specific purpose of building software specifications. And with that, we'll look at some of the major features of DokuWiki - handling changes, revisions, and drafts.
Now that we're comfortable with the wiki in general and DokuWiki in particularly, it's time to configure and customize. First comes basic configuration, discussing how configuration works and what things you might want to change immediately. Then, we'll customize DW, installing templates and plugins to make DokuWiki do what you need it to do.
And now it's time to deploy to a production server - either a box under your control or a shared host. We now have a live, working wiki.
The second section of this book are made up of standalone chapters; each addressing a specific topic that can be read by itself.
First we'll look at what's going on under the hood - investigating all of those folders and files in a wiki, and open up the top few PHP scripts to see how DokuWiki gets started and where it heads.
Then we'll take a long, hard look at security, starting with Access Control Lists (ACLs), then investigating user management, login restrictions and various scenarios you might want to emulate, and then finally consider the use of .htaccess to restrict access to the Web server itself.
Seeing as this is 2012, it's very possible that your wiki doesn't live by itself, but rather, in an environment where it has to play nicely with others. So we'll cover how to let users authenticate against a backend like MySQL instead of requiring them to maintain yet another set of credentials just for DokuWiki. Finally, I'll show you how to set up DokuWiki to send administrative email and notifications about content changes.
The last chapter in this section is a synopsis - a cookbook recipe that summarizes these steps so you can set up your next DokuWiki quickly, and without missing anything.
So far we've just talked about the wiki itself. Isn't this about software development documentation? Well, yes. While I've endeavored to make the examples up to this point relevant specifically to the task at hand, they've still been more of an afterthought than the main focus. Now let's talk about writing, er, collaborating on software document, using this brand new widget in our utility belt as our primary tool.
What we've set up is the infrastructure that's well suited for developer documentation. The trouble is that, unlike, say, accounting, where there's a generally accepted method to doing a balance sheet, there isn't a single 'generally accepted practices' for software documentation. Everyone does it their own way. In this third section, I'll discuss some ideas that you might find useful.