KB Users Guide - General Info - Questions Brand New KB Admins Should Consider

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:

• 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 an author to Publish in only one Topic via the Limited Access group feature
  
• restrict only a part of your document to be visible by a User Access group
  
• designate a specific set of documents to a specific Audience by using the Audience feature.
  

Of the Concepts You are Communicating, What are the Smallest and Most Concrete Ideas into which They Can Be Broken?

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 have the headers appear at the top of the document, or apply what we call a Table of Contents (TOC) to your document. To view an example of this, please look at this page. To apply a TOC to your document, follow the instructions here.

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.
• For managing data in MS Word, please consider the recommendations here.
  
• If you have documents in a web site you want to migrate to your KB, follow the instructions here.
  

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?

One very important aspect of this is your Title convention; 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. Style guidelines, including one of our recommended title conventions, can be found here. 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). Here is an example of the topic description from our Demo KB site. Follow the instructions here 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.

See Also:

• KB User's Guide - General Info - Entering a Lengthy Document into the KB