4 ms·

IMO wikis are anti-pattern. They always getting out of sync and eventually abandoned. Just store markdown files under the /docs/ folder in the git repo.

joshSzep 4y ago
Would you do the same with onboarding docs, system design docs, meeting notes, etc?
- nivertech 4y ago
  > onboarding docs yes, if they're don't change frequently by non-technical people. There are tools allowing conversion between GDocs and markdown. So one can start with the GDoc at the initial non-tech collaboration stage, and once it's more or less stabilized, convert it to markdown and commit to a git repo. > system design docs yes - see C4-PlantUML[1] > meeting notes no, unless they're directly code related like ADRs [2,3]. Although, one can abuse Github Issues + comments for this, in my opinion it's better to use modern SaaS tools in this case, e.g. Loom, Descript, otter/gong, etc. - you can automate this process, e.g. transcribe the meeting's recording and add the issue/repo using Github Actions. > etc. To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format. I even store visual non-text based diagrams (non-manually editable XML) using Draw.io VSCode extension [4], or Miro board backups/dumps. Use linters and automate with CI/CD (e.g. Github Actions). Also I suggest to have a list of VSCode extensions for each text/diagramming format used in the repo. Maybe with the script to automate their installation. -- [1] https://github.com/plantuml-stdlib/C4-PlantUML https://github.com/plantuml-stdlib/C4-PlantUML [2] https://adr.github.io/ https://adr.github.io/ [3] https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html https://docs.aws.amazon.com/prescriptive-guidance/latest/arc... [4] https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio https://marketplace.visualstudio.com/items?itemName=hediet.v...
  - joshSzep 4y ago
    > To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format. You have me sold, friend.

joshSzep 4y ago

Would you do the same with onboarding docs, system design docs, meeting notes, etc?

nivertech 4y ago
> onboarding docs yes, if they're don't change frequently by non-technical people. There are tools allowing conversion between GDocs and markdown. So one can start with the GDoc at the initial non-tech collaboration stage, and once it's more or less stabilized, convert it to markdown and commit to a git repo. > system design docs yes - see C4-PlantUML[1] > meeting notes no, unless they're directly code related like ADRs [2,3]. Although, one can abuse Github Issues + comments for this, in my opinion it's better to use modern SaaS tools in this case, e.g. Loom, Descript, otter/gong, etc. - you can automate this process, e.g. transcribe the meeting's recording and add the issue/repo using Github Actions. > etc. To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format. I even store visual non-text based diagrams (non-manually editable XML) using Draw.io VSCode extension [4], or Miro board backups/dumps. Use linters and automate with CI/CD (e.g. Github Actions). Also I suggest to have a list of VSCode extensions for each text/diagramming format used in the repo. Maybe with the script to automate their installation. -- [1] https://github.com/plantuml-stdlib/C4-PlantUML https://github.com/plantuml-stdlib/C4-PlantUML [2] https://adr.github.io/ https://adr.github.io/ [3] https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html https://docs.aws.amazon.com/prescriptive-guidance/latest/arc... [4] https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio https://marketplace.visualstudio.com/items?itemName=hediet.v...
- joshSzep 4y ago
  > To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format. You have me sold, friend.