C H A P T E R  11

Documenting for End Users and the Production Team

by Dani Nordin

Documentation is one of those things that many designers and developers hate doing, but it's important—not only for the happiness of clients and editors who have to take over a site but also for preventing the production team from making the same mistakes over and over again.

This chapter will give you an overview of creating effective documentation for Drupal project teams. Ideally, you'll be creating documentation for a specific site's eventual editors and administrators while also creating in-house documentation for the production team to help increase the efficiency of their workflow. I'll also discuss some ways that members of the Drupal community have found to create documentation for the benefit of their fellow Drupallers—and how you can do the same.

What Makes Good Documentation?

While there's no set formula for good documentation, there are a few things to bear in mind when creating your documents. Good documentation:

• Is easily editable and evolves with the site.
• Is consistently formatted so you don't have to reinvent the wheel every time you add to the documentation (includes visuals such as screenshots).
• Covers the most common things users need to worry about—preferably in the order that they need to worry about them.
• Discusses common errors users might run into and how to troubleshoot them.
• Is written in simple English.

That last point is the most important to bear in mind when creating documentation, whether it's for a client site, a Drupal module or theme, or your team's internal documentation. This is not to say that there's no place for code or technical requirements in documentation; rather, it's to say that it's important to assume that your end user is not the expert that you are but is willing to gain that expertise if you're willing to give it in a way that makes sense to them.

Getting Clients into Content Entry Early

Since content curation, creation, and entry form such an important part of any Drupal site, it's important to get your client's intended content team to start entering content into the site as soon as possible. Doing this accomplishes several key goals:

• It gets the development team into the habit of rapidly iterating prototypes.
• It gets the client accustomed to interacting with the Drupal interface.
• It helps identify areas that need tweaking early in the process, which makes development easier.
• It gives the client a sense of the complete development process. Ideally, it moves them away from concerns about aesthetics (i.e., what things look like) and toward user experience and functional concerns—until it's truly time to talk about aesthetics.

This last point is the most important reason to get clients involved in the entry process early. It is easy for clients to get stuck on choices about fonts, colors, and images early in the site planning process. For the design process to work efficiently and produce effective results, that's a habit that both clients and designers need to break early and often.

The best way to get clients involved early in the content entry process is to set up a staging server (e.g., staging.newsite.com) on a password-protected URL as soon as you have a working prototype of the site. A staging server is a “work in progress” version of your web site; it allows both clients and the development team to see how a project is progressing and prevents the world from seeing the work as it's happening on the production (i.e., live) site. For more on this, check out Chapter 13.

If you set up a staging server, by the time the site goes live, your client's content team will (ideally) have enough experience with managing content in their Drupal site that it will become second nature. So why create documentation after the fact? The answer is simple: people change jobs. The person who's entering content into the site now isn't necessarily going to be the only person who enters content into this site until the end of time. Having good end user documentation, in the form of a PDF (or better yet, internal Wiki in a hidden area of the web site) that you deliver to the client, is an important way to create client good will. It also prevents anguished phone calls from the new client editor down the road.

Creating End-User Documentation Post-Launch

The best, and easiest, way to create effective documentation for clients is to do it during the site building process as soon as certain areas of the site have been approved. While every site is different, the key areas that should be covered include:

• Information on how to log into the site, including login URL, username, and password.
• A brief overview of the administration menu and any shortcuts that you've set up.
• How to add content and how to format each content type. While it can seem repetitive to include an entry in the documentation for each content type, getting into the habit can be extremely useful—especially for clients who aren't terribly tech-savvy.
• If applicable, information on how to create new users and how to assign them roles.
• A brief overview of the menu system and how to add/remove menu items.
• A brief overview of the taxonomy system and how to add/remove terms.
• A brief overview of the block system and how to add/remove blocks.

Note that the last three items are somewhat controversial. Many developers resist giving clients the level of control over their site's architecture and menu/block system that access to blocks, menus, etc. will offer—with good reason. However, experience shows that clients expect and often demand that level of control; after all, part of the reason they choose a content management system such as Drupal is that they want the ability to manage their content without having to call their web team.

For this reason, it is important during the development process to create ways for site editors to manage things like menu items and taxonomy without destroying the rest of the site. By using permissions, you can do the following:

• Allow site editors to create new taxonomy terms, but not new vocabularies.
• Allow site editors to create new menu items, remove, or move around menu items, but not create new menus.
• Allow site editors to create and place new blocks, but not change Views.

Another important thing to think about during the production of your site is how users will be entering content into the site. While WYSIWYG editors (such as the buttons you use in Microsoft Word to format copy) can be a controversial topic among Drupal site builders, it is safe to assume that almost any site that you build will eventually be managed by someone who isn't a site builder. Content editors for Drupal sites often include business owners, secretaries, interns, and volunteers. Some may be tech savvy, but it isn't fair to your clients (or your team, who will have to field support calls from confused site editors) to insist that clients learn HTML in order to enter content into a plain text editor. Clients expect some sort of WYSIWYG editor, and it's important as site builders that we give it to them. Fortunately, the WYSIWYG module (drupal.org/project/wysiwyg) supports multiple different libraries. For more information, check out Chapter 4.

The Anatomy of Good Client Documentation

Good documentation should be:

• Written in language that is easily understandable by people with a baseline of technical knowledge. Assume they don't know HTML.
• Easily updated by the development team as parts of the site change.
• Comprehensive; it covers everything that the client's management team is going to have to deal with when managing the site.

For these reasons, I use a simple word processing program such as Microsoft Word or OpenOffice to create site documentation. For the documentation team, it gives them the ability to create documentation quickly and to easily update it when the site changes. The files are delivered to the client as a PDF file, which helps ensure that things don't get deleted accidentally down the line.

The process of creating documentation is equally simple, but often requires a slight shift in thinking for someone who's used to being nose-deep in code. The basic process is to do everything that a site editor would have to do—from creating a new piece of content to changing a menu item to adding a taxonomy term—and document the process with screen shots.

For example, here's a bit of sample documentation from the site that we built in Chapters 1 and 8.

SITE DOCUMENTATION :: DGD7.ORG

Documenting for the Development Team

While client documentation is an essential piece of the Drupal development process, the importance of internal documentation for development teams can not be understated. As smart people, it's incredibly easy to keep things in our heads—which makes sense when we're the only ones touching things, but causes problems when other folks come into the picture, especially on larger projects.

Team documentation can take the form of almost anything from internal Wikis (which can be created using MediaWiki (www.mediawiki.org/wiki/MediaWiki) or built in Drupal!), to intranets (check out openatrium.com for a team intranet solution built in Drupal), to shared Evernote notebooks or Dropbox folders full of random code snippets. When creating your documentation, the most important part is to think of not only the team you currently have, but the team that you ultimately want to have. Teams grow; old members leave, new members come in. Having good internal documentation gets new team members up to speed quickly and helps avoid production bottlenecks.

The most important, and most difficult, factor in creating good internal documentation is creating a logical organization for it; having everything stored in a common location is important, as is adding comments or references for code snippets, blog entries, and other pieces of documentation you decide to save. Lastly, it's important to periodically look through documentation and weed out old or outdated information. Drupal evolves constantly, as does the team's development experience. The point of documentation isn't to cover everything you've ever done, but rather to compile a list of best practices that the team can share among themselves.

Good internal documentation should cover:

• Code snippets that the team uses over and over again, with a description of the use case.
• Idiosyncrasies with specific modules and what the team did to fix them (bonus points if you contribute the code as a patch to the module!).
• A site launch checklist, which covers commonly encountered issues (and how to recover from them) for launching sites.
• Site “recipes” (combinations of specific modules and configurations) for commonly built sites.
• Locations of commonly used files, modules, site configurations, and base themes (more on theming in Chapters 15 and 16).
• Coding and development standards shared by the team.

There are as many ways to organize documentation as there are ways to make macaroni and cheese. While the flavors may change depending on what you put in, the key ingredients are always the same: you can use any kind of cheese or shape of macaroni, but you still need cheese and macaroni.

Documenting for the Community

While contributing code is a great way to contribute to the Drupal community, contributing quality documentation is arguably even more important. Good documentation is essential not only for current Drupal site builders and designers in helping them work through sticky issues, but it helps new site builders ease into creating sites in Drupal, which makes the community stronger.

There are several ways that Drupallers can contribute documentation back to the community. One of the more popular ways is via webcasts; for example, the Lullabots (lullabot.com) have a number of paid and free webcasts that cover concepts related to working in Drupal. Bob Christenson's MustardSeed Media video podcast (mustardseedmedia.com/podcast) is a great way to get used to theming and working with display modules. The screencasts offered by Drupaltherapy (www.drupaltherapy.com/screencasts) focus on site building by using recipes of specific module combinations. Without people like these folks making the content that helps us learn how to use Drupal, many smart and talented designers and developers would not be part of the community.

So, if you are working in Drupal and you learn something new, blog about it or do a screen cast. If you find something that doesn't work with a module, contribute it to the issue queue on drupal.org or mention it on Twitter. And don't be surprised if you get an e-mail one day thanking you for your contribution.

The More You Know

Good documentation isn't about adding more work to an already busy schedule. It's about helping your clients, yourself, and the community enjoy the great sites you made with Drupal. It's about avoiding frantic midnight e-mails from clients who can't figure out how to add a page to the site. It's about saving the next Drupaller from the headaches you've been dealing with as you struggle to get a certain module or theme to work. It's about broadcasting a cool trick you learned in that one site that you wish you remembered now. Good documentation helps everyone. The sooner you start compiling it, the better.