{"id":9187,"date":"2021-11-28T17:10:28","date_gmt":"2021-11-28T17:10:28","guid":{"rendered":"http:\/\/TheNextWeb=1374349"},"modified":"2021-11-28T17:10:28","modified_gmt":"2021-11-28T17:10:28","slug":"how-to-build-a-dev-knowledge-base-ahead-of-your-next-job","status":"publish","type":"post","link":"https:\/\/www.londonchiropracter.com\/?p=9187","title":{"rendered":"How to build a dev knowledge base ahead of your next job"},"content":{"rendered":"\n<p><em>Disclaimer: this is not an ad for Obsidian.<\/em><\/p>\n<p>Onboarding to a new company is hard work. Keeping all the information straight is its own work stream that deserves thought and attention. Countless names, faces*, teams, initiatives, and acronyms fly by before noon. Believe me. I\u2019m in the process right now. This week I landed on a system I\u2019m pretty happy with.<\/p>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/graph.png\" alt=\"Obsidian graph\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/graph.png\" alt=\"Obsidian graph\"><\/noscript><\/figure>\n<\/p>\n<h2>You\u2019re a knowledge worker. Build a knowledge base<\/h2>\n<p>You need a place to put all the information you\u2019re receiving. This is some of the stuff I\u2019m talking about:<\/p>\n<ul>\n<li>People<\/li>\n<li>Teams<\/li>\n<li>Repositories<\/li>\n<li>Relationships between teams, repositories, people, etc.<\/li>\n<li>Initiatives<\/li>\n<li>Your work product and tasks<\/li>\n<li>\u201cPlaybooks\u201d for common tasks<\/li>\n<li>Daily agendas<\/li>\n<li>Meeting notes<\/li>\n<li>Ideas<\/li>\n<li>Questions you need to ask someone<\/li>\n<\/ul>\n<p>I recommend <a href=\"https:\/\/obsidian.md\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Obsidian<\/a>. It\u2019s essentially a markdown editor\u2013but it\u2019s so much more than that. It\u2019s open source. It works off of your local filesystem\u2013no cloud-based privacy concerns. It encourages you to create a dense knowledge network with many links and tags. It also has a rich set of <a href=\"https:\/\/help.obsidian.md\/Plugins\/Core+plugins\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">official<\/a> and <a href=\"https:\/\/obsidian.md\/plugins\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">community plugins<\/a>.<\/p>\n<h2>Plant seeds<\/h2>\n<p>It can be quite intimidating to start from an empty directory. But, you don\u2019t have to build your knowledge base manually. Try seeding from available data sources.<\/p>\n<h3>Engineering wiki<\/h3>\n<p>Does your organization have an engineering wiki on GitHub? Clone it and dump it right into your Obsidian folder. Now you have tons of pages instead of a blank slate.<\/p>\n<p>You are your company\u2019s foremost export on onboarding. No one else remembers what it was like to onboard, and\u2013especially if they onboarded a long time ago\u2013the experience could be quite different, now. You can use your vantage point to make the next hire\u2019s onboarding experience better. Contribute to the wiki as you\u2019re onboarding. Make it less confusing.<\/p>\n<p>I recommend checking out a branch of the repo so that any changes you make are PR-able. One really easy change that adds a ton of value is just adding hyperlinks. There\u2019s often an obscure page describing something that doesn\u2019t have any links going to it. Hyperlinks are a better discovery tool than grep, so add them.<\/p>\n<h3>Github repos<\/h3>\n<p>Add a markdown file in your knowledge base for every repo at your org. If you use GitHub, download the GitHub CLI. From there you can generate a JSON file of the top \u2018n\u2019 <a href=\"https:\/\/cli.github.com\/manual\/gh_repo_list\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">repos<\/a> at your organization\u2026 if you can, maybe just get all of them. They are ordered by most recent commit.<\/p>\n<pre><code>$ gh repo list [yourorgname] --limit 1000 --json name,description,createdAt,updatedAt`) &gt; your-repos.json<\/code><\/pre>\n<p>I wrote a little node script to generate markdown files too.<\/p>\n<pre><code>const { writeFileSync } = require('fs'); const repos = require('.\/your-repos.json'); const pathToObsidian = '...'; function renderMarkdown(repo) { return `# [${repo.name}](https:\/\/github.com\/yourorg\/${repo.name}) &gt;&gt; whatever you want here, description is nice...&lt;&lt;`; } for (const repo of repos) { writeFileSync( `${pathToObsidian}\/repos\/${repo.name}.md`, renderMarkdown(repo) ); } <\/code><\/pre>\n<h2>People and teams<\/h2>\n<p>This one is harder to make generic. At my new job, I found a pretty good list of the engineering org in Google Groups, copied the html table from the browser into Google sheets, then exported a CSV. Your source of truth might be Slack, GitHub Teams, or something totally different. You can also add people manually.<\/p>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/person.png\" alt=\"Create profiles for each person you meet with\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/person.png\" alt=\"Create profiles for each person you meet with\"><\/noscript><\/figure>\n<\/p>\n<h2>Version tracking<\/h2>\n<p>Use git. Git init in your Obsidian directory. We use git for everything else, why not our knoledge base? Commit at the end of every day and take a look at the diff. Write a real commit message. Don\u2019t worry about length. For me, it contains a better summary of my day than I can find anywhere else.<br \/><code>$ git log<\/code> is now a pretty great way to see what you\u2019ve done in a week.<\/p>\n<p>Just make sure you have a .gitignore file. In my case I ignore my eng-wiki directory so I don\u2019t have to deal with git submodules.<\/p>\n<h2>Diagrams<\/h2>\n<p>A picture is worth 1000 words. Here\u2019s how I do pictures.<\/p>\n<h3>Excalidraw<\/h3>\n<p>There\u2019s <a href=\"https:\/\/github.com\/zsviczian\/obsidian-excalidraw-plugin\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">an Excalidraw plugin<\/a> for Obsidian (thanks @zsviczian!). I\u2019ve already written about <a href=\"https:\/\/offbyone.us\/posts\/why-is-excalidraw-so-good\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">how much I <em>love<\/em> Excalidraw<\/a>. The fact that Obsidian can elegantly integrate with Excalidraw is amazing. When I say elegantly, I mean it. You can link from inside diagrams to pages inside your knowledge base. You can embed. It\u2019s great.<\/p>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/excalidraw.png\" alt=\"Excalidraw\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/excalidraw.png\" alt=\"Excalidraw\"><\/noscript><\/figure>\n<\/p>\n<h3>Mermaid<\/h3>\n<p>Excalidraw is a great general purpose diagraming tool. But, for highly structured diagrams, <a href=\"https:\/\/mermaid-js.github.io\/mermaid\/#\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Mermaid<\/a> is sometimes better. Obsidian has native support for Mermaid diagrams. Just make a code block annotated as \u2018mermaid\u2019.<\/p>\n<p>Here\u2019s an example from their docs.<\/p>\n<pre><code> flowchart TD A[Start] --&gt; B{Is it?}; B -- Yes --&gt; C[OK]; C --&gt; D[Rethink]; D --&gt; B; B -- No ----&gt; E[End]; <\/code><\/pre>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/mermaid.png\" alt=\"Mermaid\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/mermaid.png\" alt=\"Mermaid\"><\/noscript><\/figure>\n<\/p>\n<h2>Questions<\/h2>\n<p>1,000,000 questions will come up every day. There won\u2019t always be time to ask them. Some of them you can look up. I recommend making a system for these. I made a central questions page. When things come up on other pages, I link to my questions page. That way, when I want to review open questions, I can go look at all the backlinks. Tags also work.<\/p>\n<p>Every day take a look at open questions. Look through the company wiki, or other sources of truth. If you find the answer, update the link from <code>[[question]]<\/code> to <code>[[answered-question]]<\/code> and include the answer with any hyperlink to existing content in the knowledge base. For example, <code>[[answered-question]] what's the protocol for opening PRs into other teams' repos? Answer: [[eng-wiki\/code-review-process]] goes into this.<\/code><\/p>\n<p>For questions you can\u2019t answer for yourself, filter them to only those which matter and your team can answer, and Slack them en masse, each day. Make sure the answers make their way back into your knowledge base.<\/p>\n<h2>Daily notes<\/h2>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/dailynote.png\" alt=\"Daily note\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/dailynote.png\" alt=\"Daily note\"><\/noscript><\/figure>\n<\/p>\n<p>Obsidian has a <a href=\"https:\/\/help.obsidian.md\/Plugins\/Daily+notes\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">daily notes plugin<\/a> that is very useful. First thing in the morning, I create a daily note, enter my google calendar agenda (hyperlinking to everyone I\u2019m meeting with). I always include a \u2018meta\u2019 section for observations about how the system is serving me. I also recommend creating links referencing the <a href=\"https:\/\/forum.obsidian.md\/t\/fun-with-espanso\/2317\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">next and previous day<\/a>.<\/p>\n<p>I find that daily notes end up accumulating a ton of random stuff that came up that day. Take a little time to ask yourself if content on the daily note page should be relocated.<\/p>\n<h2>Tickets<\/h2>\n<p>At least early on, every task you\u2019re assigned in your product management could also be tracked in your own personal note system. It allows you to link to relevant docs, take notes, draft status updates, gather questions, make diagrams, etc.<\/p>\n<p><figure class=\"post-image post-mediaBleed aligncenter\"><img decoding=\"async\" class=\"aligncenter js-lazy\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/ticket.png\" alt=\"Ticket\"><noscript><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/offbyone.us\/img\/knowledge-base\/ticket.png\" alt=\"Ticket\"><\/noscript><\/figure>\n<\/p>\n<p>My tickets directory isn\u2019t flat. Mine looks like this:<\/p>\n<pre><code> tickets \u251c\u2500\u2500 closed \u2502 \u251c\u2500\u2500 POP-696.md \u2502 \u2514\u2500\u2500 POP-698.md \u2514\u2500\u2500 open \u2514\u2500\u2500 POP-700.md <\/code><\/pre>\n<p>Having the distinction between open and closed helps at standup when you want to tell your team how the ticket is going.<\/p>\n<p>Many of the tasks you complete when you\u2019re new on the job are somewhat rote. You\u2019re not re-architecting the home page in week one. For these repeatable tasks, is there good documentation about how to do it? Probably not. Make a playbook. It\u2019ll make it easier to do next time. If your playbook describes something beyond just you and your team, add it to the eng-wide wiki.<\/p>\n<h2>Retros, free writing, and synthesis<\/h2>\n<p>If your team does retros, I recommend calendaring some time beforehand to do free writing. Even if your team doesn\u2019t have a retro tradition, scheduling some time for free reflection is a great idea\u2013it encourages synthesis, connections, and understanding.<\/p>\n<p><em>Think of it as part of your job description to minimize entropy.<\/em> After you understand the ball of yarn that is your organization, you can untangle it, or at least reduce the rate at which it tangles. You can come up with analogies, diagrams, connections \u2014 anything that makes the system fit into brains better \u2014you will add tremendous value. <a href=\"https:\/\/distill.pub\/2017\/research-debt\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Here\u2019s a great article about this general idea<\/a> as it applies to researchers. They call it research debt. I think of it as <em>semantic debt<\/em> or <em>cognitive debt<\/em>. Reflective writing is a good way to prepare your brain for synthesis.<\/p>\n<p>When you write reflectively. Don\u2019t worry about formatting and linking while you free write, it could get in the way of flow. Once you\u2019re done, see if there are links to add or formatting to apply.<\/p>\n<p><em>*It doesn\u2019t help that I have prosopagnosia!<\/em><\/p>\n<p><em>This article from <a href=\"https:\/\/offbyone.us\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Off-by-one<\/a> is a stream of thought about computers. The author, Zeke Nierenberg, writes about programming, education, tech-enabled thinking tools, and product development. Find the original article <a href=\"https:\/\/offbyone.us\/posts\/new-job-knowledge-base\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">here<\/a>.<\/em><\/p>\n<p> <a href=\"https:\/\/thenextweb.com\/news\/how-to-build-developer-knowledge-base-ahead-next-job-syndication\">Source<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Disclaimer: this is not an ad for Obsidian. Onboarding to a new company is hard work. Keeping all the information straight is its own work stream that deserves thought and attention. Countless&#8230;<\/p>\n","protected":false},"author":1,"featured_media":9188,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[1],"tags":[],"_links":{"self":[{"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/posts\/9187"}],"collection":[{"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=9187"}],"version-history":[{"count":0,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/posts\/9187\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=\/wp\/v2\/media\/9188"}],"wp:attachment":[{"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=9187"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=9187"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.londonchiropracter.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=9187"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}