: Documenting a Mongo Collection Field While writing some documentation I stumbled upon the need to describe the location of a field in a Mongo Collection on one of our corporate servers. After

Vote Up Vote Down

How do you document X?

It depends on who's going to read the document.

As a rule of thumb I use to look at my documentation from two perspectives; the system perspective and the audience perspective.

The system perspective deals with what system is being documented, and if several systems should be dealt with in one document or if a system should be documented on a per-sub-system level.

The audience perspective deals with who your audience is. You will usually see the following:

End users - want a non technical "user guide" description of the system
Programmers - want information to be able to change or extend the code of the system
Maintenance personnel - want information on how to maintain (stop, start, backup, relocate etc) and sometimes configure the system

Other kinds of users like testers and support personnel usually want information from several of the above document types, but they are usually able to spend more time figuring out the system.

Each audience should have their own document. It's very seldom a good idea to put all different perspectives in one document unless the system is really small.

Once I know what system I am documenting and for whom, I think "use-cases" (kind of); What would an end-user need to know to use the system? What would a programmer need to know to change the system? What would I need to know if I was one of these people trying to perform their tasks?

(0)