Guidelines/Template for Documentation

[jmiskey]

We have an environment where we will have a Development Team, and an Administration team.   What we need to do is when the Development Team completes a project, they supply the Administration team with some documentation on what was developed, i.e. the logic behind it, what they need to know to administer it, and the knowledge that will allow them to trouble-shoot it.

Does anyone have any guidelines or templates on what should be included in the documentation and how to best structure it?

Thanks.

[darius_koohmare]

Currently, this is what I've seen commonly done:

Using Demand Management / a Custom App to track all configuration requests, kind of like this example: Creating a Configuration Logging System - ServiceNow Express Support

Using knowledge management and maintaining a specific KB around 'using the platform', and documenting platform logic by application (e.g. incident, change, etc.) and function (e.g. business rules, ui policies, client scripts, etc.).

Once you move to Jakarta, I highly recommend your admin documentation processes include guided tours / embedded help.

Embedded help and guided tours

Using Guided Tours to enable users on fields, features, and usability.

Getting Started with the Guided Tour Designer in Jakarta

Jakarta will also allow the definition of embedded help content by roles, so you can have in-context information presented to your users.

Embedded help

[jmiskey]

I am not quite sure that is quite what I am looking for.   Configuration tracking may be somewhat helpful from a technical standpoint.   And Guided Help is more of a on-line help for users on what to fill out.   It may be more of a "Knowledge Management" type thing, but what I am trying to figure out is if there are any guidelines, best practices, etc. for creating such articles.

Think of it this way.

If you hired a consultant to build an application for you, what kind of documentation would you expect to get back?   That coupled with documentation from our side regarding business purpose and workflow.

So, we are looking for something that we could give a new ServiceNow administrator who was just hired who doesn't no anything about a particular application that they would need to support.   It should include things like:

- description of business purpose

- workflow explanation

- architecture

- etc

So it should provide them with enough information to support and trouble-shoot the application.

It just seems like such a big, wide-open endeavor, I am not sure where to start.   So I was interested to see what others may have done, to this effect.

Thanks

[smooradian]

This would be great to see if you get a response.