# Being Handsome in Tech A tale of struggle --- ## Documentation Geek Drink [](https://www.youtube.com/embed/wBSJ2Dhr3nM) Note: - A quick clip ---- ## John Hector Casillas ### Cloud Engineer ---- ## Outline 1. Why documentation is important 2. What good documentation looks like 3. Some best practices 4. Crowdsourcing Documentation Note: - The idea of this Geek Drink is to host a forum to discuss documentation. I'm going to discuss some topics that are important to me, and what I would like to see every team move towards, but that requires input from the whole team. --- ## John's Documentation Stack 1. [Obsidian](https://help.obsidian.md/Getting+started/Download+and+install+Obsidian#:~:text=Install%20Obsidian%20using%20Snap,you%20downloaded%20the%20installation%20file.&text=Open%20Obsidian%20the%20same%20way%20you%20would%20open%20any%20other%20application.,-Install%20Obsidian%20using) 2. [Miles' MD -> Confuence Tool](https://github.com/justmiles/go-markdown2confluence) 3. [Confluence](https://gofigg.atlassian.net/wiki/spaces/~62390a2fee1b5a007027ab57/overview) 4. [docs.gofigg.io](https://docs.gofigg.io/) Note: - Show Obsidian, Daily Notes, Jira Integration, MarkdowntoConfluence --- ## The Power of Documentation ---- | Docs Effectiveness | Title | | -------- | -------- | Good | Jurassic Park | | Bad | Memento | | Bad | [John's Terraform Notes](https://gofigg.atlassian.net/wiki/spaces/~62390a2fee1b5a007027ab57/pages/1579745329/Terraform+Notes) | | Good | [Miles' Marketplace Restart](https://gofigg.atlassian.net/wiki/spaces/~miles.maddox/pages/104331714/Restart+Marketplace) | ---- # Jurassic Park: > Summary: Island theme park of real dinosaurs. What could go wrong? - Centralized Document Repo (in the storage room) <!-- .element: class="fragment" --> - Easily read by all skill levels (John Hammond and Malcolm) <!-- .element: class="fragment" --> - Precise - able to not only step-by-step Ellie through process, but *navigate* her there too <!-- .element: class="fragment" --> ---- # Memento > Summary: Protagonist suffers from amnesia, and compensates by leaving himself notes and clues. - 3 different documentation types (notes, pictures, tattoos(don't recommend for work docs)) <!-- .element: class="fragment" --> - The engineer himself can't discern what he's talking about <!-- .element: class="fragment" --> ---- # John's Notes - Only useful to John - Could be several individual docs - Adds chaos - No flow  ---- # Miles' Notes - Easy to read - Flows - Searchable  --- ## Elements of Effective Documentation ---- [Github:](https://google.github.io/styleguide/docguide/best_practices.html) 1. Minimum Viable Documentation 2. Update docs with code 3. Delete Dead Documentation 4. Documentation is story of your code Note: - Keep it simple - If you update your code, get into the habit of updating your docs with the Changelog. - Yea john - You're writing docs for humans first and computers second. ---- [Chromium:](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/documentation_best_practices.md) 1. Minimum Viable Documentation 2. Update docs with code 3. Delete Dead Documentation 4. Prefer the good over the perfect <!-- .element: class="fragment" --> 5. Documentation is story of your code 6. Implementation state determines document repository <!-- .element: class="fragment" --> 7. Duplication is evil <!-- .element: class="fragment" --> Note: - Same thing but adds "Prefer the good over the perfect (technically in the last one but not in their bullets)"" - If the doc is about implemented code, put it in README.md. If it's pre-implementation discussion, including Design docs, PRDs, and presentations, keep it in shared Drive folders. Thoughts on this? - Do not write your own guide to a common technology or process. Link to it instead. --- ## Documenting Best Practices Implementing the Elements ---- - "Stream of Conscious" notes <!-- .element: class="fragment" --> - Have a public dumping ground <!-- .element: class="fragment" --> - Review and then ask your team or manager for specific feedback (if you think it's necessary) <!-- .element: class="fragment" --> - [Cool Commits](https://www.microverse.org/blog/how-writing-meaningful-commit-messages-helps-you-be-a-better-developer) <!-- .element: class="fragment" --> - [Rad READMEs](https://google.github.io/styleguide/docguide/READMEs.html#guidelines) <!-- .element: class="fragment" --> ``` OPS: Currently creates module to create anomaly detection against every account and optionally a stack. [SRE-1488] [type] [optional scope]: [description] [optional body] [optional footer] ``` <!-- .element: class="fragment" --> Note: - Miles - anything to add on stream of conscious? - Cool commits - I was doing really trash commits, and a lot of them per ticket. - Rad READMEs - Something I learned more about writing this geek drink. (We use tf docs, but is it enough?) --- ```bash git_flatten () { git reset $(git merge-base master `git branch | grep '*' | cut -d ' ' -f2`) git add -A echo "#############################################################################" echo "# Write your new, singular commit message, and then force push to origin." echo "# Like this:" echo "# git commit -m 'COMPRESSED_MESSAGE'" echo "# git push -u origin $(git branch | grep '*' | cut -d ' ' -f2) --force" echo "#############################################################################" } ``` --- ## Conclusion - John's Personal Style: - Uniform commit style - Document everything, clean up later - No secrets. - Do you have any must-have rules? <!-- .element: class="fragment" --> - How do you document today? <!-- .element: class="fragment" --> - Would you rather have poor docs or no docs? <!-- .element: class="fragment" -->