Who is your audience?

Consider each audience or population for whom you are creating documentation. How much (or more importantly, how little) do they know? This is important for making sure content is written as simply, clearly, and concisely as possible. This may also relate to the access controls you’ll ultimately apply to the documentation, such as:

• restrict documents to the Internal Live Site (authentication needed)
• set document access to the External Site (accessible to public)
• restrict to a specific User Access group
• limit certain users to only seeing documentation on a particular topic via the Limited Access group feature
• restrict only a part of your document to be visible by a User Access group
• identify a set of documents as specific to a certain group of users via the Audience feature.

Of the concepts you are communicating, what are the smallest and most concrete ideas you can break them up into?

This goes along with the above question—you want to break up information into easily digestible parts (distinct and individual documents), then link them together via the See Also and Up, Previous and Next features. That way, if someone is only looking for the answer to one question, they can find it easily in one document. Should they need more, you can always direct them to additional information in other documents.

You may also divide a document using an H2 or H3 headers and add a Table of Contents section to your document. You can create a Table of Contents yourself, or you can automatically create one based on your headers.

Do you have documents that will be transferred from a shared drive, another web site, a wiki, or data in MS Word form?

Think about the documents that are in other parts of your organization. Carefully consider what you want to bring over. Make a phased plan which includes:

• Who will determine what documents will be moved from document repository X to the KB?
• Are documents being moved into the KB in the most current and up-to-date state?
• If not, will they be updated by a KB Admin via the In Review queue once they are in the KB?
• Are there images, logos, icons that need to be readily accessible for documents? If so, upload them into the Shared Attachments folder so they can be accessed from within any document in the KB Admin Tools.
• Will you be copying and pasting content from MS Word and Google Docs?

Is there information that will need to be repeated or reused throughout multiple docs?

An example of information that may appear in multiple docs:

• Common steps in navigating an application
• Contact info
• First few steps in a protocol

It is more efficient to create these pieces either as page headers, page footers, or docs and attach or include them via the IncludeDoc in your documentation. Page headers, page footers and/or the document embedded via the IncludeDoc only need to be updated once and will subsequently appear updated in all the documents in which they have been applied. This way, you will not unnecessarily repeat work, and you won't have to worry about multiple sources of the same information.

What should be consistent across all documentation?

For example, we recommend thinking about the convention you will use for document titles. We always recommend deciding on a consistent title structure, as this makes it easier for end users to scan the search results table when on the Live Site. For tips on this, please see our style guidelines. If there are certain groups of documents that might benefit from consistent sections/headers, consistent information and/or formatting in each field, you may also want to consider creating templates.

Under which subject areas will your content fall?

Think of all of the content you plan to publish and sketch out some plans for how a topic tree might look. This could involve meeting a few times with your various content experts and coming up with several options for how the tree is modeled on a physical whiteboard. The KB has 5 topic levels, but no limit to the number of topics in a given level. The more you can decide on up-front, the less you will have to change later.

When your users search the Live sites (Internal and/or External sites) for a Topic, you may create a document very explicitly describing what the Topic is and is not. This description will appear above the table of documents yielded in a search of your Live Site(s). Follow the instructions to create a Topic description of your own.

Training Considerations

The training covers quite a lot of material, so we’d recommend including everyone if possible, especially for the Author Training session. We often find that for closely-working teams, training tends to generate some questions about how you might want to leverage certain features, so having the full group is definitely a plus. That said, if scheduling ends up being an issue, a recording can be made for you to send to anyone who can’t attend training in-person. Please review this workflow sheet to see what the best workflow for your group may be.