Whether you are an individual or a large team, having an established set of principles for documentation is critical to ensure longevity, sustainability of the documentation. Just as brand and style guides serve to keep the integrity of the product, documentation guidelines keep the integrity of the documentation.

When working with a team of people to write documentation, the guidelines that you adopt are ultimately based on your needs. Drupal.org, for example, has a “Documentation” role that allows that user to freely edit documentation posts and add pictures to their additions. Technically, anyone with a Drupal.org user account can edit documentation, but the user's access to certain pages is limited based on access to text formats with security implications. The documentation role provides access to most of these, but a few pages that define policy are further locked down. As usual, the larger the team or individuals that are contributing, the more imperative it becomes to establish guidelines.

Make sure that your guidelines for documentation are easily accessible and read by everyone. In short, documentation guidelines will help others make your documentation better.

Tools for creating and maintaining documentation

Choosing a tool for creating and maintaining documentation can be daunting because there isn't one tool that is better than other. In fact, the best tool is the one that you will actually use. When deciding on a tool, there are some good points to take into consideration to ensure selecting a good fit.

• How large is the team? A large team has different needs than a small team or an individual. Managing shared Dropbox folders of text documents can be unwieldy for large teams but work extremely effectively for smaller teams.
• How often is there turnover?
• What tools does the team comfortable with? It might seem silly but it is easier to gain adoption when the entry barrier isn't foreign or completely unknown.

There are some good features to look for when deciding on tools:

• Select a tool that manages revision history. Revision history is important for individuals and teams. It is also a fantastic way to keep a record of the documentation evolution, critical for learning and knowledge advancement
• User management

There are many tools out there to choose from. The following list are mostly free, low-cost tools. Open Atrium or Wikis are my personal tools of choice.

• Drupal: A Drupal installation can quickly turn into your own documentation site
• Open Atrium: Open Atrium, created by Development Seed, is a tool for managing communication. (@TODO: example of how to use atrium for documentation). Web based system.
• Wiki: Wikis are incredibly effective for documentation creation and management. Wiki syntax is fast, almost everyone has had exposure to a wiki (ex. Wikipedia); they are collaborative tools by nature; they track revision history. Wiki's are web-based systems.
• Evernote: Evernote notebooks can be shared with anyone that has an email address. Free versions restrict users with access to just view mode, purhcased plans allow users to edit. Evernote has tags to help categorize content and revision history. Evernote is great tool for mainting collections or snippets of code information that can be organized into notebook collections and tags. Multiplatform and web-based.
• Dropbox: Dropbox is good if you are choosing to build your documentation in text files. Folders can be shared, but requires that all participants have a Dropbox account. Dropbox is a hybrid off- and online approach. Dropbox tracks revision history.
• Screen capture tools: There are a myraid of tools available from browser extensions to standalone programs. Some common ones: Sitch, Google Chrome, Firefox.
• Video: Many people prefer screen capture videos demonstrating use of a site feature over text documentation.

If you have the time, try out various tools. The solution that works best for you and your team could also be a hybrid of some of the options listed above. Whatever your solution, once you've established “Where” you will document, you need to focus on “How” to document. In the next section we look at the importance of establishing a logical organization to your documentation.

The principles of what makes good documentation and tools for documentation apply to all forms of documentation. For the rest of the chapter we will focus on documentation needs and nuances of three user-groups: the end-user, the production team, and the community.

Documenting for Editors and Site Administrators

One of Drupal 7's strong points is its revamped user experience for the end-user and for the administrator. More often than not, such users are overlooked; enhancements to the administrative interface and workflow come secondary to the site. We tend to do very little beyond what Drupal provides. Now thankfully Drupal 7 provides a lot; its revamped user experience—from customizable admin toolbar to the overlay—can make it tempting not to think you have to change much. It can seem daunting or almost impossible to budget time to making improvements, but it will save the client money down the line. Don't forget that their experience and ability to maintain the site is what makes the users of site experience and developers and designers work come to life.
The anatomy of good client documentation
End-user documentation follows all the points listed in earlier section “What makes good documentation”. When it comes to end-user documentation it is important to stress that documentation is written in language that is easily understandable by people with a baseline of technical knowledge--assume your end-user don’t know HTML. Additionally, the following points will help you build better end-user documentation:

• Build as much documentation into the site interface
• Update the description of content types to reflect how they are used on the site
• Change the default help text to support the site
• Hide sections and options that don't serve end-users needs. This can be handled on a per role basis. For example: if your end-users don't have any HTML knowledge, they don't need to the option to change the input type when entering content. Additionally, WYSIWYG toolbars can be configured to only provide the necessary formatting options to end-users.
• Make sure to cover everything that the client’s management team is going to have to deal with when managing the site
• Involve the end-user in the creation process (the following sections cover this point more in more detail)
• Be open to changes from the client
• Think Back to Basics. Remember that your end-users might not have any Drupal or content management experience. Remember what it was like when you first started.

The process of creating documentation is not complicated, 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 these reasons, I tend to use a straight word processing program, like Microsoft Word or OpenOffice, to create site documentation. For the documentation team, it gives them the ability to create documentation quickly, and 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.

Don't wait until the end to start documentation

The best, and easiest, way to create effective documentation for clients is to do it during the site building process. Iterative documentation creation ensures that documentation a) actually gets written, and b) that the documentation written is usable. While every site is different, there are key areas that will need to be covered for most sites. In fact, because these key areas are so universally common across sites that I strongly advise writing a documentation primer that you can reuse for all clients. This document is then extended to cover the unique needs of the site. Common key areas worth include:

• Information on how they log into the site, including where they go to, and what their username and password is.
• A brief overview of the administration menu, and any shortcuts that you’ve set up;
• How to add content, and how content is formatted for 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.

A brief comment on the last three items, as they can be controversial. Many developers resist giving clients the level of control over their site’s architecture and access to blocks and with good reason. However, experience shows time and time again 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.

The level of freedom and control granted to end-users is based on the needs of the client and goal(s) of the site. Developers and designers should engage in conversations with the client about this early in the planning process. Take into consideration their level of expertise. Allowing end-users more freedom to manipulate and place information is so common that in the past years a number of really good modules have been developed to handle the balance between granting freedom to non-developers and preserving the integrity of the site. For more information, I recommend Context Module (@TODO link here) and Panels module (@TODO link here).

Involving People in the Documentation

Getting clients involved in the process will more than likely require changes to how you approach project planning and development process. You will need to plan for time to review the administrative interface as part of your release cycles and/or development process. You might have to make changes to your staging and deployment process. Setting up a staging server is a fantastic way to allow 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 the chapter on Staging and Deployment.

Don't get discouraged if you don't get it right the first time. Each project will help you refine your process, prepare and learn from unknowns and ultimately discover the best method that works for you and your team. Don't be afraid to solicit feedback from your end-users!

The approaches we've outlined aim to enusre that 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. These approaches help save you and your client time and potential anguish. 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-- people change jobs, interns get hired, and used for things like updating the website. Finally, these approaches help strengthen and build client relations. By taking the time to build documentation and involve the client in process you demonstrate a care and concern for their needs and site.