Documentation concept
So we have all been there - assigned a simple task that eventually became a horrific experience to implement due to lack of documentation on extensive customization done in the past. In this article I will try to convince you that writing a documenation is a necessity, even for complicated servicenow projects. I will also show you how to leverage out-of-the-box features to make sure that your documentation is easily usable and visible in the right spot.
Idea
Of course, there are many ways and many tools to document our work - every developer has a favourite. But let's consider this for a while - since we are already working on ServiceNow platform, shouldn't we also at least try to use it as a source of project documentation? There are couple of points to support this solution:
- We know the platform well enough to facilitate and even make documentation mandatory if necessary
- We can easily make sure that every feature is documented
- We can leave something nice for future consultants in an environment that they know and have access to
- And finally it is really easy to do this, as I will show you in this article
But remember, this is just a proposition - I understand that many of you may already have well-defined internal processes or are restricted by customer rules. And also remember that I assume you are developing on dev instance. I prefer to keep my technical documentation out of business user's reach.
What do we need?
As I said, it is really easy to start writing something about our work on ServiceNow Platform. We need:
- Knowledge Management plugin (currently using com.snc.knowledge3)
- Contextual Search plugin (currently using com.snc.contextual_search)
- A bit of configuration
That's it! 3 easy steps to make your (or your developer's) work much easier.
Solution
First, we need a separate knowledge base with categories that best describe what you will be documenting (i.e. Update sets, Business rules, ...). Let's call it Technical documentation.
The best part of this solution is that you can define your process how you like - you can add review/approval steps, select managers. And by default we have commenting, suggesting and Q&A at zero additional cost!
Next, let's create a search context. Go to Contextual Search > Search Contexts and create new record. You can select all options as you like.
Once this is done, we need a table configuration for every table which records we want to document - update set, script includes, business rules, ... This requires a bit more work, but is rewarding in its elegance. The most important thing is to select proper Search context. You can adjust options as you like. Once submitted, go back to our new configuration and add Search Fields on related list. Remember that you can only select text fields! And at least one field has to be default. Optionally, you can also add Filter Configurations - in case below, I added single filter to only display results from particular knowledge category.
Next step is to add Contextual search results objects to form layout. Do it by simply updating the form layout on the table you have configured for contextual search.
And you are all set! The only thing to do is to create knowledge articles, publish them and enjoy your documentation!
Future development
With this solution, you have the freedom of adding modifications and specific rules - because you simply know how. You could, for example:
- Write business rule to force developer to create KB article for every new object,
- Report on documentation coverage
- Facilitate the onboarding of new developers
- Use it for the training of business users
- Automatically update KB articles when documented object is updated
- Create nice sprint summaries
- Allow developers to write object's description in HTML
- Link one object to another (via search results)
- Automatically attach documentation to stories
- ...
Conclusion
Hopefully, I gave you an idea how you can leverage the platform features to prepare documentation. I am aware that this is yet another documenting tool, but this one seems (to me personally) the most suitable option for any servicenow project, especially for support duty.
