Knowledge height

and finally that question came out: “why don’t we move that info from company wiki page to source code repository README?”

I remember the very first XP team I joined almost 15 years ago, our workspace was full of informations, such as visible metrics about the project, and even shared mottos printed on A4 sheets that the team liked to remember. one of those was “for any question, ask to (1) the source code, (2) the wiki or (3) the team“. the order was that important. and year after year, company after company, team after team, I have to confess that motto is still running inside my veins.

indeed, I ended up being one of such “wiki gardeners” out there (I’m sure we are a horde), not because I missed the number one “source code” alternative, but because much of the things that I found the need to write down was one step above the individual source code repositories I had to deal with (even while still trying hard to keep one single repository for much of related projects, but that’s another story).

for example, current (and past) initiatives or projects the team was involved to: people involved (and how to contact them), bunch of planning resources (release plans, decks, planning tools), third parties documentation, some minimal HOTWOs or FAQs for common admin tasks.. you get it. and also some technical documentation about involved applications: main architecture pictures (boxes and lines, lanes for internal/external ownership, etc — you could also evaluate any public model for this), source code repositories, environment endpoints (eg: development, QA, production) and main locations (eg: /health, /cache, etc).

so that question arise: is that the proper place where to put such technical information? would it be better to keep it closer to source code? even better, why don’t we generate on-the-fly from live resources? for example, we could rely on Swagger/OpenAPI documentation for individual APIs. even further, we could aggregate live dependencies between applications, and graph them on real-time (former colleagues did this with a bunch of traces parsing, a graph database a some simple queries to plot on a dashboard).

yes, but what about keeping in the repository README in the meanwhile, so that they’re less likely to be stale? sure, that’s a great idea! so in the end, it’s a matter of a threshold (as usual). my personal rules of thumb:

• are those info involving one application only? keep them in the README, but consider chaching them in the wiki for a broader audience (non tech people, with no access to source code repos, in the case they need it). examples: environments, endpoints, APIs, even build instructions
• are those info involving more than one application? find a “lowest common denominator” where to place them (similar to what front-enders do with reactjs state :) just kidding). alternatives could be some dedicated pages on the wiki (of course), or even some shared repository for architecture or infrastructure documenting. examples: architecture diagrams (very same hint I have with Architectural Decision Records, being in a central repo instead of on individual repos)

and now it’s time to refactor your knowledge base, making an height instead!

PS: happy new year folks, it could’t be worse than the past one (even if January was not so promising).