At Nansen, creating editor documentation is part of our development process. Regardless of how user friendly a CMS is, an editor's first interaction with a it can be daunting. In this post, I wanted to share how we implement our editor guides. The example I am going to go through is with Episerver, but we have used the same process with many other CMS frameworks.
When we write our editor guides
Our editor guide process usually begins at the end of our development process. It gives us as developers a chance to get out of the development headspace before creating the documentation. This has two benefits: First, it helps us write more user-friendly guides. I am sure you have had that experience where you just get done developing a new feature, and you try to explain it to a member of the team. Their eyes tend to glaze over, and you end up needing to figure out how to explain it to someone who didn't have their head buried in the code. Writing the documentation at this phase helps avoid that unneeded complexity in our guides.Second, it can serve as a form of testing. Taking a second look at the implementation from that other point of view is always helpful. It may help you catch something before it gets to the QA team. This is not even necessarily a bug in the code. But it could just be catching something that, after a second look, might not be exactly what the editor is expecting from a functionality standpoint.
How we format our editor guides
We usually house our documentation in Confluence. This can vary from client to client based on their needs. It gives us the flexibility to export as PDFs as well if client's do not wish to work with Confluence, and prefer hard copies.In Confluence, we create a page for each content type. As you can see in the photo to the left, we group our pages into two categories, block types and page types.Each content type page in Confluence consists of screenshots for both the rendered page, its corresponding edit view, and a brief summary of the page. Here is where we would also provide any links to product requirements associated with that content. The screenshots are annotated to map the properties in the CMS to what appears on the page.From there, we go into describing each property. We make sure to include not only what the property does, but what happens when it is not filled out (Does the content fallback, change how the page renders, etc.). 
Testing our editor guides
Once we finish our editor guides, we hand them to our Quality Assurance (QA) team along with the site for testing. They use the guides to assist them in running through their test cases. This allows them to provide feedback to us as developers based on their usage during testing. If they have any issues working with content, we know that the guides need to be revised. We treat any of these updates as bugs that need to be fixed during the QA process.
Getting them to the editor
The next step is figuring out the best way of delivering the documentation to the editor. Usually, this is as simple as providing access to our pages in Confluence or sending a PDF of all the pages. We have also provided clients with more complex implementations. I previously wrote a post about including the documentation as a view in the CMS.Even though at this point the client has the documentation and is well into the editing process, that does not mean we are done. Whether its change orders that update the original project scope, or new features requested long after the site launches, we make sure our guides stay up to date.
Final Thoughts
From devs, to QA, to our clients, the feedback on this process has been positive. We are always of the belief that more documentation is better than less. And while documentation might not be the most glamorous part of development, we find that once its integrated into your process, it turns into something that is low effort/high reward. While we have found this process successful, we know there can be many ways to accomplish the same goal. If you have any thoughts on our process, or think we would benefit from hearing about your process, please feel free to comment below.
Top comments (0)