How do you document or maintain your change log and advanced customizations?

[nmartinez]

When I first joined the ITSM Team as a ServiceNow developer, I inherited two years of advanced customizations that were written by at least six different developers. We had many performance issues, and bugs and overtime we found that some of our issues were due to customizations my predecessors made, and as I started to make my own customizations to the out-of-the-box code I too came across code written by my predecessors that I could not figure out what it was supposed to do, or why they had developed it in that method, and some of them prevented me from doing what I needed.

Now, fast-forward two years later; I am coming across advanced customizations that I wrote as a rookie; and I am finding myself asking "What was I thinking?", "Why did I write it this way?" "What does this actually do?".

When I first started I didn't do a great job at commenting my Java Script; I wrote clunky workflows and I invented hacks to force SN to do what I needed from it, and now that same code has come back to haunt me.

We have four developers on our team, and we all have a wide-range of experience from basic to expert and I want to find a way that we can all document our work, keep notes as to what the functions do, why we're doing it, and so on; so that anyone in the future can look at our work and with little study time understand what we did, how and why.

I was thinking about developing an application within SN itself to document and track our work. But from a design-point-of-view, I am not sure where to start.

What do you do in your team to track your work and document your code?

[Ben_Little]

I built out a "Documentation" table in Service Now with fields such as architect, description, users, training links, etc. For us, it was important to be able to not only understand what the documented application itself does, but what each of the rules/scripts behind the scenes does. Therefore, I put a lot of fields on the Documentation form, to describe the overall function, inter-dependencies, training, limitations, as well as reference fields and lists to the changes that put the application into production, updates sets used, enhancement requests for the app, etc.

I also added a related table to track document revisions, with standard version/changes/author/date type fields.

In addition there are about a dozen related tables that link to each of the most common scripting/access tables, so I have intermediary tables for Business Rules, Script Includes, UI pages, Scheduled imports, Scheduled jobs, View Rules, UI macros, Client Scripts, ACLs, UI Scripts, UI actions, Email Notifications and even Workflows associated. I just chose those that we were most likely to need to know about.

Here is an example of the Client Scripts intermediary table (Doc Client Scripts):

These tables are like the built-in 'user has roles' table, in that they have reference fields to the main Documentation, as well as reference fields to the script table (e.g. Business Rules) without being a direct link to the script itself. This allows us to add things like Description, etc., without modifying the native table, and allows a different description of how the Script is used with each Application documentation set. It also allows quick navigation through the Application documentation to get to every script added or modified.

Finally, Since it is really a PAIN to have to remember what you wrote or edited for each application you are documenting, I wrote a UI Action on the Local Update Set table, which parses through a committed update set, and finds all scripts/pages/macros modified in that update set, and adds those to a Documentation Record in each related list. This way, at least you know you had some modification to X Client Scripts, for example, and you can then go through a write a short description on how each is used in the application. On massive updates sets that have spanned the months needed to build an entire application, this has been invaluable.

Hope that helps.