Tag Archives: itknows

ITKnows, HelpDocs and TeamDynamix KB

I had feedback today that the recent reorganization of content in ITKnows has caused some trouble – particularly where articles had been linked elsewhere (e.g. in Canvas) and the articles were later combined into guides.

As of a couple months ago, we had over 400 articles in ITKnows, many of them were repeats, and given our reorganizations over the Summer, the layout no longer made sense. With help from Todd and others we worked to collapse those articles into guides organized by topic, clarified the categories into which new articles should go, added templates to facilitate creation of new content, archived duplicates, and published many articles that were pending review.

The reorganization of documents in ITKnows is done, now, for the most part. Things should not continue to move. However…

TeamDynamix has a built-in knowledge base that comes with several benefits. (It has some limitations, too.) One of the benefits is that we can put all of our documentation – public and private – in one place, meaning we only have one place to search across both sets. TD’s KB also has the concept of Article IDs, which will make linking to and sharing documents easier.  Referencing an article by ID number gets us away from the problem of linking to a URL that might one day change.

We are in the process of reviewing the features of TD’s KB right now, and I do not plan to immediately move our ITKnows content there. What we have in ITKnows is working for the most part. However, we are looking at TD as a possible new location for the HelpDocs pages. An important dependency for that is to have the TD client portal enabled, and we are hoping to have that accomplished by January. HelpDocs is currently on Drupal 6, and I think is higher priority at this time.

One issue I am aware of for the new format of the guides in ITKnows is that you cannot do a Ctrl-F and search the page to quickly locate content. The guide format looks nice, but is not friendly for quick reference. I will be working on some alternative layouts to make that easier. It’s worth mentioning that if TeamDynamix’ KB looks like it is going to be a winner, we may end up moving our internal documents there soon. I just don’t have enough experience with it yet to speak to that, and don’t want to over-promise.

So, TL;DR:

  • I will be working on the guide format to make searching in ITKnows easier.
  • I’m sorry I broke your links. It was necessary to get ITKnows under control. The breakage should not continue until/unless we move to TD’s KB.
  • We are evaluating TD’s KB as a replacement for HelpDocs (customer-facing documentation) first so we can get off of Drupal 6.
  • The client portal needs to be turned on for TD, and that should be happening in the next few weeks.

Let me know if you have questions or concerns about documentation that I have not addressed.


Changes to ITKnowS!

Over the last month or so we have been making some changes to ITKnowS.

The first change you will probably notice is that the main ITKnowS! page has been updated to provide a more concise view. The ‘Area Guides’ block near the top was removed after a quick poll of primary ITKnowS! users determined it was no longer useful for looking up documentation. This allows the ‘Article Categories’ section to float up to the top of the page and leaves room to add an additional informational widget in the near future.

We made a few adjustments to improve usability as well. In an effort to make information related to a specific topic easier to find, we are in the process of consolidating the multiple existing topic documents into a single source. The consolidated document will be in either an InfoSheet format containing all of the particulars on a topic, or in a guide book format that better separates out sub-components of more involved documentation. The Article Categories have also been condensed and updated to better align with the decided document types. This will allow for easier classification of articles and quick access to all posts within a specified category from the ITKnowS! main page. The current categories, and what type of documentation they are associated with, can be found below.

  • Applications – Stand-alone software applications.
  • Departments – Departmental information sheets.
  • For Review – Built-in category for newly created articles.
  • Hardware – Server, printer, computer, and other hardware articles.
  • Policies – Internal and external policies.
  • Processes – Internal and external processes and procedures.
  • Reference Materials – General information only articles.
  • Services – Internal and external services provided to users.
  • SMS Equipment – SMS check out equipment.
  • Tools – Internal tools (generally web-based) that are used to complete day-to-day operations.

The remaining updates were made to assist with the document creation process:

  • Pre-formatted templates have been created for each document type that include when it is appropriate to use a given template and what to fill in the Title, Category, Tag, and Anchor fields.
  • The Writing Guide has been updated to include information about how to use templates to create new articles.

We will be continuing to fine-tune the documentation process based on feedback form all of you, and looking for additional ways to leverage the features of WordPress to best meet our needs.


Note: a huge “thanks!” to Todd for all his work on the new templates, categories, and guides. Also, thank you to Samuel for all the work to get this tool up and running for our team.