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 spending a bit of time on this I arrived at the following: mongodb://user:pass@host:port/database.collection.field

How do I document data structures in Mongo?

disclaimer: If this out of scope, It was suggested that I might find help in this SE HERE
(if this incites strong emotions, please vote there too!)

  • What have you done to research this question? What examples have you considered and would you point them out to us? – rolfedh Feb 6 '16 at 1:49
  • unfortunately its been difficult because search results for mongo "documentation" yield a lot of information about mongo "documents" instead. I found some generic endpoint documentation examples for MySQL and piecing together what is said about mongo connection strings allowed me to arrive at the result in `code markup' above. thanks in advance. – Shanimal Feb 8 '16 at 18:15

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?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.