Skip to content

Instantly share code, notes, and snippets.

@caligin

caligin/README.md

Last active March 29, 2018 12:17
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save caligin/88c5e0f9de0fd0fce4d899c06e82e121 to your computer and use it in GitHub Desktop.
Save caligin/88c5e0f9de0fd0fce4d899c06e82e121 to your computer and use it in GitHub Desktop.
Download ZIP
documentation repo readme template
Raw
README.md

documentation

architecture decision records (ADRs), diagrams, explanation of processes, any other reference material and reports of past issues never solved

table of contents

  • architecture-decision-records

TODO: this can probably become a template+makefile combo (see actual-cookbook for reference)

how to use this repo

few guidelines:

  • use markdown: textual, simple and github renders it nicely for free
  • curate commit messages: they're the tool to keep track of change so make them communicate
  • use consistent terminology: allows simple search tools like "find in page" and grep to be highly effective
  • be concise: nobody likes to read or write documentation when documents are as long as the lord of the rings
  • explain reasoning: presprictive statements can become dogma, explaining reasonsing allows to challenge past decisions in a changing future
  • source for binaries: if you have source files for binaries commit them as well to enable reproducibility (e.g. the xml export of a draw.io diagram as well as the png)
  • don't ask for permission, ask for reality check: if you want to edit or add anything just go ahead and do it but make sure that what you're writing is understandable and not your unilateral opinion
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment