search

OCHA-DAP / hdx-signals

HDX Signals
https://un-ocha-centre-for-humanitarian.gitbook.io/hdx-signals/
GNU General Public License v3.0
6 stars 0 forks source link

Technical docs #157

Closed caldwellst closed 5 months ago

caldwellst commented 5 months ago

Technical docs! Tried to at least get the top level directories started for your review. Good to finish these up and merge, then build in more detail as necessary so that we don't have the current docs sitting on main.

hannahker commented 5 months ago

Awesome to have these! 😍 Overall, the content makes sense to me and is an excellent improvement.

A couple high level points for discussion:

  1. Level of detail

Big picture, it would be good to discuss the level of detail that the think is appropriate/necessary for our technical documentation. I'm a bit concerned about creating too much maintenance burden for ourselves by having too much detail. For example, I think that describing the functionality of each script in READMEs is probably not necessary, since we have pretty descriptive script names and good documentation within each script. It's a super slippery slope since as soon as one piece gets out of date, we/others will lose trust in the documentation altogether. It's a tough balance to strike... My feeling is that we're a bit too far into the detailed side of things

  1. Getting started with developing

How should new contributors get started with running the system? Which scripts provide an overall entry point? These points took me a while to understand when I started working on this project and so I think would be useful to have explicit guidance around. This should also include a summary of the testing environment variables and how someone would use those to work locally.

zackarno commented 5 months ago

yeah i think @hannahker has good points on "level of detail" as well as making sure the "entry point" for developing/debugging/understanding is clear.

Nonetheless, no objection to merging and iterating over those and other details as we go?