How to use Jama for Documentation

Collaboration & Alignment

How to use Jama for Documentation

By |

My absolute favorite feature of Jama is the Review Center: I love the ability for teams to collaborate on work without sitting in a room or emailing around a Word doc. We posit the Review Center as a place for requirements to be reviewed and signed off on by stakeholders, but it can be used any time consensus is needed between one or more people. The Support team uses the Review Center for crafting internal knowledge base articles and processes, as well as Community articles. I have seen a few customers and prospects ask if Jama can be used for documentation, so I thought I should share how my team uses it. Let me know if you have any questions.

Why does Support review articles this way? Can’t someone just write it and call it good? Nah! Here are the reasons why we use Review Center.

  1. We tend to have strong opinions but want to get on the same page.
  2. We want to create readable articles for our customers (and ourselves!), and peer feedback is the best way to ensure our writing will make sense to a broad audience.
  3. It is easy to forget a step in a tutorial—or maybe the writer doesn’t know the most efficient way to do something—and peer review helps us write thorough documentation.
  4. I used to be an English teacher, so I have a special place in my heart for peer reviewing and editing and how it strengthens both the writer and the reviewer’s communication abilities. (And to be honest, I miss using a red pen.)

Here’s a high level overview of our process:

  1. Designate a project or component for documentation work. All of Jama’s departments have their own project, but we also share cross-functional projects. Support has a project that we use for documentation work and tracking work we share with other teams. We keep the documentation in a component called Support Knowledge Base, which we further break out into Internal and External. This helps us keep track of the intended purpose of an article while reviewing it; we apply the same content and style standards regardless of its final home. Review Center
  2. Track article tasks and ideas somewhere. You could readily use Jama for this—as various colleagues have article ideas or tasks, they could briefly outline it in a Task item type in Jama (we do this for the Help Guide). In Support we enter article ideas in JIRA because that’s where we track all of our non-ticket work. As support engineers solve tickets, they select Yes or No on an Is Community Post or Internal Document Needed? drop-down. Our scrum master then enters these tasks into our backlog, and these get assigned during sprints depending on what other work we have.
  3. Draft the article in Jama. We have been focusing effort in recent years on quality, useful content. This includes examples, workflows and lots of screen captures. For consistency’s sake, we abide by a style guide that relies on various technical writing tenets AND the belief that our customers are smart and capable. Once the article is coherent and covers the requirements outlined in the task, the writer prepares for review.
  4. Start a Review. We start the review by inviting pertinent stakeholders—realistically we don’t need everyone on the team to review every article. We ask the question “Who is affected by this article?” If it’s an internal process doc, we invite only those support engineers it affects. If it’s a community article, we invite those on the team who would know most about the topic. For this initial review cycle, we start with a four-day window for new article reviews and a three-day window for article update reviews. At this point we do not highlight grammar and style errors—it’s important to get the content nailed down first.
  5. Evaluate the feedback provided and respond to it. If you don’t agree with a suggestion, reply to the feedback within the review explaining why. If you do agree, make sure to select Agree or Acknowledge when you make the change. Reviewing articles can be time-consuming, so it is as much about respecting the time someone spent looking at the article as it is ensuring no feedback is missed.Review Center
  6. Apply the first round of feedback and create a new revision. Edit the article, applying all accepted changes. Submit a new revision to the stakeholders until they all approve the content. We don’t have a cap on the number of revisions an article can go through—some of our community articles have had one hundred comments and eight revisions.
  7. Send your article to final style and grammar review. This round is typically shorter, as it is mostly grammar and style. We have a couple of grammar fiends on the team and a well-defined style guide to follow, so this round is really about making sure we are putting our best (and consistent) foot forward. Like the content round of revisions, this round will include as many revisions as needed until the final reviewer provides an approval.
  8. Publish your article! This can be the most frustrating part of the process, as web-based rich text editors notoriously play terribly together. If you’re lucky, you can copy the article or source HTML from Jama and paste it into your destination’s editor. If you are incredibly unlucky, you might have to plain-text paste into the destination editor and go through the formatting rounds again.

If you’re new to Jama reviews, I recommend watching our Ask Jama session which covered the functional aspects of Review Center. If you want to try something new in Review Center, I recommend the Ask Jama session about Rolling Reviews. Don’t forget that you can sync up with other customers (and me!) in our Support Community if you want to ask questions or trade tips! There are other Jama features to consider as well when establishing a process like this, such as Workflow and exporting to a printable format.

Kristina King
Latest posts by Kristina King (see all)