I am working with a project team that hired a contractor to build a custom GeoDjango webmap application. The application is mature now and the team would like to host it on our network "in-house". I'm responsible for writing the contract deliverable to get the technical documentation (something that was overlooked during the building of the application, before I was hired here).

How much detail should I be looking for in the technical documentation? Currently, the github site has some sparsely commented installation instructions and nothing else. But, if a few months down the road I need to get under the hood to add functionality, how much documentation should I expect? Aside from the full technical specifications, what are the key details that are must haves to facilitate a smooth transition?

I need to make sure this captures everything we'll need to know moving forward. Right now I have a very generic:

Create basic training materials for new users in the form of a user manual as well as technical documentation providing full specifications of the technical stack…

  • Having a huge doc containing everything is not necessarily easier to read than the code (and it is a pain to maintain, meaning the code and the detailed doc will often not match). – JGH Jun 28 '18 at 14:19
  • "full specifications of the technical stack" means a 1 pager listing the technology name and version – JGH Jun 28 '18 at 14:20
  • Yes. I guess I'm wondering is there any middle ground between a list of the tech and a massive doc I'll never open? – mikeLdub Jun 28 '18 at 14:22
  • 2
    I personally put a lot of value in data flow graphics: main input/output, main modules/function required, main decision switches. I also avoid putting any code in the doc. This applies at multiple levels (app, modules etc). Ex: Get user address - is address already geocoded? -> Yes: return current XY No -> geocode -> return new XY. Then have another one for the geocode module and for determining if the address is already geocoded or not. – JGH Jun 28 '18 at 14:29
  • 1
    Documenting is essential when creating data/software. If it is not a dupe, I think it would be nice to have one in GIS SE. I don't think it is primarily opinion-based. There are best practices and good technical advice when choosing how and what to document. – Andre Silva Jun 30 '18 at 14:41

Your Answer

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

Browse other questions tagged or ask your own question.