https://www.joshcanhelp.com2021-11-01T00:00:00ZJosh Cunninghamjosh@joshcanhelp.comTaking Notes: Why and How2021-11-01T00:00:00Zhttps://www.joshcanhelp.com/notes/I've been writing for myself regularly for probably 15 years and have tried out many different systems and apps. Recently, I think I finally found the right one.<p>I've been writing for myself regularly for probably 15 years or so. Whether it's journaling or taking notes while I learn something or just keeping references, I find both the act of taking notes and the output to be extremely valuable for me.</p>
<p><img src="https://www.joshcanhelp.com/_images/2021/taking-notes.jpg" alt="" /></p>
<p>Taking notes keeps me focused on the task or meeting or thought that I'm exploring and help me to save my place if it goes on for more than one session. I also find that it solidifies the experience in my head and helps to identify the important parts. After the activity itself, notes can provide an important record for myself and others if they get published somewhere. My notes often turn into posts and documentation on my site or internally (see <a href="https://training.kalzumeus.com/newsletters/archive/do-not-end-the-week-with-nothing">Patrick McKenzie's thoughts on producing artifacts</a>).</p>
<p>The more notes you take, though, the more "stuff" you have to look through when you need a reference in the future. I just recently spent a couple of days going through and cleaning up what I have and I was surprised by the number of similar notes and overlap that I found between all of the different places I've stored my writing. Once you've felt the pain of trying to find something you're sure that you wrote about, you might find it painful again to start a note on something in the future. You can feel yourself causing more pain in the future by writing more. That's not a good place to be in when you want/need to write and the cognitive load of "where do I put this so I can find it later" can stop you from even starting another note.</p>
<p>I wrote a long time ago about <a href="https://www.joshcanhelp.com/information-reservoirs-or-how-i-keep-track-of-a-large-amount-of-incoming-information/">information reservoirs</a> and it's still quite relevant for this notes problem. If you have a thought or a link or a picture you want to keep and find later, you want to think very little about where to put it. Part of reducing that thinking is knowing you can find it later, if not easily then just not too painfully. If everything you might save has a place and everything you do save can be found, this system works. It's a bit like Marie Kondo's philosophy of everything having a place: if you bring home something that does not have a place, then you either give it a place, you get rid of the thing, or you just start to build clutter.</p>
<p>I've been working on refining how I take and store notes, partly because I never felt settled into a system and partly because the number ways to do this seems to have expanded quite a bit recently. The idea of building and managing a "personal knowledge base" or PKB is something that I'm seeing more and more people writing about and, as such, I've been thinking about it a lot recently as well. I think everyone would benefit from getting their thoughts into words on a regular basis but I do acknowledge that maintaining this kind of system is one part productivity and one part hobby.</p>
<p>I've worked my way through a number of different systems and applications over time with varying levels of commitment and success. I think the one I just started using, <a href="https://obsidian.md/">Obsidian</a>, is as close to perfect as I've found and I'll explain why in a little walk-through video at the end.</p>
<p>I started with just text files in directories. I started writing notes before there was a big push towards storing your data online or in the cloud. This was also before you could be all that productive on your phone so note-taking on-the-go was reserved for only the most ... desperate. <a href="https://www.joshcanhelp.com/the-search-for-a-new-cell-phone/">My experience looking for a new phone in 2009</a> will help make the reasons why more clear. If I was writing for myself, I was on my desktop computer at home or a computer at school. I would save my notes to a USB, sync when I was home, and rely on my backups in case I lost the drive.</p>
<p>At some point someone turned me on to <a href="https://brettterpstra.com/projects/nvalt/">nvALT</a>, a small app for organizing your notes and seeing them all in one place. I think around the same time I started using Dropbox and the combination was somewhat mind-blowing. I started taking a lot more notes and saving more text snippets from sites and articles that I found. I felt like I was more efficient creating and finding my notes, so I started using it more. The app didn't sync anything anywhere, it just organized a bunch of text files that were stored in a certain directory so it wasn't much different from how I was doing it before.</p>
<p>I kept with this system for a long time because it worked and because it was simple. Apps like Evernote and OneNote and came out and I tried that but it just wasn't for me. I wanted mostly plain text stored locally.</p>
<p>Then someone told me about <a href="https://workflowy.com/a/">Workflowy</a> and I was, once again, totally blown away. Workflowy is basically one giant bullet point list that lets you focus in at any point of the tree. Imagine all of your notes and references and everything all in one massive document and then setting what amounts to bookmarks at places where you want to jump back in. I realized that 95% of my notes and references were bullet points and that the rest of my writing was just a bullet point list that didn't know it was a bullet point list yet (picture the HTML DOM). I had an honest-to-god revelation and realized that it's bullet points all the way down, man.</p>
<p><img src="https://www.joshcanhelp.com/_images/2021/html-dom-as-bullet-points.png" alt="" /></p>
<p>I started taking more notes than I ever have, saving recipes and code snippets and task lists and everything else. Between this paradigm shift/discovery and Workflowy's delightful interface, I felt like I had truly reached nirvana. When I stopped using it, I had a half-MB document containing almost 8,500 individual bullet points of notes, references, and tasks.</p>
<p>After a while, though, something didn't feel quite right. If everything could be represented as a list and all the lists were stored together in a hierarchy, you really can only put things in one place. By definition, a child bullet point can only have a single parent. You always have to find a place before you can add a new note, which means you have to kind of store a map of things in your head in order to organize this all effectively. And when it's time to add, say, a list of quotes from an article about code quality, you have to decide "does this go in the section of article notes so I can find all my notes in one place or in the section of notes about code quality?" It takes a lot of management time to make sure the system is working well.</p>
<p>But manage I did until I found <a href="https://roamresearch.com/">Roam Research</a>. Roam represented a revelation for many, many folks who take regular notes for many reasons, one of which being <a href="https://maggieappleton.com/bidirectionals">bi-directional linking</a>. When you make a link from one page to another, that link is two-way so you have an explicit link to one page and that linked-to page automatically links back. Roam goes even further and also keeps track of implicit links just by looking up all the places where you used the title of the page that you're on. Now, as you write, your system is making connections between the information without you having to do it on your own.</p>
<p>I loved this concept and felt like I had found a very important piece of the puzzle. Roam did another thing, though, that had just as profound of an impact on me and that was the idea of automatically creating daily note pages and being able to create notes in the future. This combined with automatically linking notes together means that I always have a place to put a note of any kind, the daily notes spot, and know that I can easily find that chunk of text later. Roam is also based on bullet points so my existing mental model was represented.</p>
<p>Roam Research is a very cool product and it advanced my note-taking ability and workflow greatly but two main problems - no local copy and a clunky user interface - made me feel unsure about migrating everything I had into it. That said, I have been using the heck out of Roam since May 2020 and have written more notes in that time than the 2-3 years previous combined. Bullet points, bi-directional linking, and daily notes were key to that productivity.</p>
<p>Then came <a href="https://obsidian.md/">Obsidian</a> and, for a variety of reasons, I'm pretty sure this is the app I'll stick with for many years to come. It has nearly all of the features of all the other apps I've used combined, along with an interface that gets out of my way almost completely. I now have almost 10MB of text that I've created accessible through this app making linking things together very powerful. Now that it's all in one place, the idea of a PKB is more salient than ever.</p>
<p>I walked through how I use Obsidian in the video below, hopefully that's helpful for folks looking to take their notes to another level or migrate in from another system. In the video, I cover:</p>
<ul>
<li>Daily notes and template for tasks, routines, and default note collection</li>
<li>Explicit linking when I think about it, implicit when I don't</li>
<li>Project notes and structure for periodic review and better note collections</li>
<li>Tags for lightweight grouping for paragraphs and bullet points</li>
<li>Book and article archiving and notes</li>
<li>Blog posts are symlinked so they can searched and referenced</li>
<li>Anything that is (or can be) text and could at all be useful in the future gets stored</li>
<li>Problems including quick collection on mobile and data in other systems</li>
</ul>
<p>Enjoy!</p>
<iframe width="650" height="367" src="https://www.youtube.com/embed/wXI1YVWJuhA?si=2j7-uDXP4Jw7hgJI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen=""></iframe>
<h2 class="hr" id="references">
<span class="pink"><</span>
References
<span class="pink">></span>
</h2>
<ul>
<li><a href="https://github.com/joshcanhelp/sample-obsidian-vault">Example Obsidian vault used in the video</a></li>
<li><a href="https://www.youtube.com/watch?v=7uuXbUGjRUw">Previous video walk-through is here</a>.</li>
<li><a href="https://nileswyler.medium.com/why-i-switched-a-deep-dive-into-roam-vs-obsidian-df1a394971ff">Great post that helped me make the move from Roam to Obsidian</a></li>
<li><a href="https://news.ycombinator.com/item?id=28894481">Hacker News thread with lots of comments about Obsidian, other note taking apps, and the PKB concept in general</a></li>
</ul>
Notes from Rock Your Code Reviews with Dr. Michaela Greiler2020-01-15T00:00:00Zhttps://www.joshcanhelp.com/rock-your-code-reviews-webinar/I attended a great webinar led by Dr. Michaela Greiler on code reviews. I had my own opinions going in, of course, but I learned a lot and had a number of questions that I had (and didn't know I had) answered.<p>I attended a great webinar led by <a href="http://www.michaelagreiler.com/">Dr. Michaela Greiler</a> on code reviews. I had my own opinions going in, of course, but I learned a lot and had a number of questions that I had (and didn't know I had) answered.</p>
<h2 class="hr" id="notes">
<span class="pink"><</span>
Notes
<span class="pink">></span>
</h2>
<h3>Why do code reviews?</h3>
<ul>
<li>Finding defects? Knowledge sharing?</li>
<li>Microsoft says: code improvements and finding defects</li>
<li>Unreviewed code is 2x more likely to introduce defects</li>
<li>80% of code reviews lead to code improvements</li>
<li>Only 15% of issues <em>related</em> to defects</li>
<li>What are code reviews about? (decreasing percentage of issues)
<ul>
<li>Readability - 25%</li>
<li>Organization of code</li>
<li>Solution approach</li>
<li>Validation</li>
<li>Visual representation</li>
<li>Defects - 5%</li>
</ul>
</li>
</ul>
<p><img src="https://www.joshcanhelp.com/_images/2020/01/what-are-code-reviews-about.png" alt="" /></p>
<h3>What are the pain points?</h3>
<ul>
<li>Timing - interruptions, waiting, context switch</li>
<li>Social - bullying, conflicts/attacks</li>
<li>Low feedback quality</li>
<li>Value vs speed (quadrant)</li>
<li>Want: thorough reviews delivered in a timely manner</li>
</ul>
<h2>Successful reviews</h2>
<ul>
<li>Increase process speed + reduce reviewer burden</li>
<li>Reduce reviewer burden
<ul>
<li>Microsoft:
<ul>
<li>Self-review - read through the changes before submission</li>
<li>Small reviews - small, incremental changes</li>
<li>Coherence - cluster related changes</li>
<li>Context - describe the purpose/motivation</li>
<li>Success - set-up for success through training and education for the reviewer (what should I look at</li>
</ul>
</li>
<li>Size:
<ul>
<li>Fundamental and impactful</li>
<li>200-400 LOC maximum</li>
<li>Number of files affected inversely proportional to feedback quality</li>
</ul>
</li>
<li>Microsoft:
<ul>
<li>Tests - write and run tests before submitting</li>
<li>Automation - automate everything possible</li>
<li>Tools - review tools, CI/CD</li>
<li>Skip/Indicate - skip unnecessary reviews, author indicates potential impact</li>
<li>Reviewer selection - select the right reviewer and not too many</li>
</ul>
</li>
<li>Google:
<ul>
<li>Every change is reviewed; max 4 hour review cycle š® (MS: 24h)</li>
<li>90% of all code changes comprise less than 10 files/24 LOC</li>
<li>Clear approval criteria (ownership of code and readability); 75% of reviews are approved by 1 dev</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Summary</h3>
<ul>
<li>Small, coherent changes</li>
<li>Continuous feedback cycle on code reviews</li>
<li>Automation and tools</li>
<li>Clear guidelines and policies</li>
<li>Education and training</li>
</ul>
<h3>Questions</h3>
<p><strong>Is it important for the PR itself to be small or does several small, incremental commits as a part of a single larger PR still burden-reducing?</strong></p>
<ul>
<li>Stacked commits</li>
<li>Design review activity to use separate branches (?)</li>
</ul>
<p><strong>Should test code be reviewed differently than functional code? Does that account for the suggested LOC maximum?</strong></p>
<ul>
<li>Different focus but tests need dedication</li>
<li>Flaky/non-deterministic tests are problematic, time-consuming</li>
<li>Review test code with the same rigor as functional code but different mindset</li>
</ul>
<h2 class="hr" id="take-aways">
<span class="pink"><</span>
Take-Aways
<span class="pink">></span>
</h2>
<p>This webinar could not have come at a better time. My team at Auth0 was taking a critical look at our review process and I learned a number of things that would be helpful for us to craft a better review process.</p>
<p>First, we gathered pain points from the team about our current process. We asked:</p>
<ul>
<li>What makes you nervous when submitting code?</li>
<li>What makes you nervous when submitting a review?</li>
<li>What are you unsure about?</li>
<li>What's something that you or a teammate does that everyone should do?</li>
</ul>
<p>A few examples of what we got back:</p>
<ul>
<li>Not sure how often to check the queue or how soon we can ping who we are waiting on.</li>
<li>What's the process to re-request a review? Does using the GitHub UI work for everyone?</li>
<li>Not sure how to deal with legacy issues that are not in-scope for this change</li>
<li>How do I indicate a "nice to have" change that does not block a merge?</li>
<li>What's the absolute maximum size of a PR?</li>
<li>How many reviews do we need? How do we handle mutli-person reviews?</li>
<li>Who resolves the comments, author or placer?</li>
</ul>
<p>As of this writing, we were still in the process of figuring out the details but the webinar was a big help in giving us perspective and approaches from other companies.</p>
Keys to Good Technical Documentation2019-09-08T00:00:00Zhttps://www.joshcanhelp.com/keys-to-good-technical-documentation/Summary of the best comments in a Hacker News thread about technical docs.<p>This was compiled from a <a href="https://news.ycombinator.com/item?id=20909783">Hacker News thread</a>.</p>
<p><strong>TL; DR: Examples, glossary, and reasoning behind potential surprises:</strong></p>
<blockquote>
<ul>
<li>Examples. Realistic, complete, useful examples that demonstrate the software being used in the manner it is intended.</li>
<li>Glossary for any special terminology that can't just be googled - especially project specific terminology that may be confusing, and double especially terms or phrases which are used slightly differently to the way everybody else uses them (e.g. 'user' means something slightly different almost everywhere).</li>
<li>Lots of "why" describing why the software behaves in ways that seem surprising at first glance.</li>
</ul>
</blockquote>
<p><strong>TL; DR: Work with a technical writer:</strong></p>
<blockquote>
<p>The best technical documentation Iāve seen at a company was written by a technical writer. Most companies donāt like hearing this because it costs more than adding an additional drag on your development teams to also become solid writers (good writing is real, time-consuming work). Having someone whose job it was to start from the perspective of your users, ask questions of the dev team along the way, and document the journey yielded enormously useful docs.</p>
</blockquote>
<p><strong>TL; DR: Consider the audience and the JTBD; explain the system as though in person:</strong></p>
<blockquote>
<p>I think good documentation needs to be written with a few decisions in mind: What role, what kind of person is this section written for, and what kind of task does the reader have at the moment?</p>
<p>There should be sections on familiarizing yourself with the system - which persistence APIs are used, what are the broad dataflows, where are things dispatched into greater detail, what are active parts in the system. And I did say "sections", because a developer, a system operator, a customer supporter and a consultant implementing the system all need different kinds of information and levels of detail.</p>
<p>There should also be sections on handling known task structures, known troubleshooting guidelines, again, with a focus on the role of the current reader. If content has to be searchable via elasticsearch, there should be focused documentation: How do I get an entity into elasticsearch? How do I connect an actuator setting on a pin with a setting on the UI page? These sections should be mostly like a todo-list.</p>
<p>In order to write something like that, imagine just explaining the system to someone and write most of that down. I've found that this results in very effective documentation. It's usually simple to read, and it's also easy to understand if you should read this block or not. For example, if something says "This is scoped for developers", I might skip it.</p>
</blockquote>
<p><strong>TL; DR: Create sequence diagrams:</strong></p>
<blockquote>
<p>... come up with sequence diagrams for the most common flows/use cases - sequence diagrams are the killer feature of UML - everyone gets the message.</p>
</blockquote>
<p><strong>TL; DR: Consider the maintenance required:</strong></p>
<blockquote>
<p>... the trouble with good technical documentation is it can quickly become bad technical documentation. It needs constant maintenance over the long term. Every patch that's committed to the code needs to be evaluated for how it impacts the docs. Preferably changes to the docs should be done via a collaboration with the patch author(s) and a documentation expert (aka someone who is good at writing technical documentation and is familiar with the conventions of this specific document).</p>
</blockquote>
<p><strong>TL; DR: Consider the maintenance required once more:</strong></p>
<blockquote>
<p>People hate to update docs so the majority of the time it's out of date even if it was the best ever at one time. I was never told this but reading a ball of undocumented code is part of the job so don't ever expect documentation when you start a job, especially at a startup.</p>
<p>Here are a few things that would make life easier.</p>
<ul>
<li>reduce the code's complexity.</li>
<li>easy to update</li>
<li>Summary of the software's function</li>
<li>Major sections of the code should be titled and explained as briefly as possible in code.</li>
<li>Docs should be part of the code review. I had a software package that would fail if the code was updated and the comments had not or the other way around. It was easy to disable but at least it made you think.</li>
<li>Buy in from the management on keeping docs up to date. Very hard, managers want results not docs</li>
<li>Regular review of the docs.</li>
</ul>
</blockquote>
<p><strong>TL; DR: Documented tests, module explanation, basic docblock hygiene:</strong></p>
<blockquote>
<p>Well-documented tests. Why are you testing something? Why do you expect the output to be something? What is the high level purpose of the test?</p>
<p>High level breakdown of the code structure. What is each module / package / namespace intended for?</p>
<p>Aside from that, then just the basics:</p>
<ul>
<li>all functions (or all exportable functions) have consistently formatted docstrings</li>
<li>docs are concise most of the time, but overly verbose in any ādangerā sections of code that rely on unusual, specific or brittle logic.</li>
<li>well documented description of project version control. What are all the usual code management tasks someone needs to do, and why? What is your strategy for hotfixes, releases, rollbacks, sharing branches, etc.</li>
</ul>
</blockquote>
<p><strong>TL; DR: Donāt do the job of code comments and keep it simple:</strong></p>
<blockquote>
<p>Documentation should explain why things are the way they are. With sufficient effort, you can look at a piece of code to figure out what algorithm it implements, but there is no amount of reading that will tell you why that algorithm is the right one to use. There should be a way to trace this "why" all the way up to the business reason.</p>
<p>Documentation should provide mental shortcuts. Rather than forcing you to figure out what algorithm the code implements, it could just tell you.</p>
<p>Documentation should tell you things that are surprising, and might accidentally miss or misinterpret.</p>
<p>Documentation should tell you information that you can't just as easily glean from the code.</p>
<p>Documentation shouldn't attempt to tell you everything with one form of documentation. Documentation on a line or method or class is good for one sort of information, but it doesn't cover the overall architecture of the program. That is often best left as a separate piece of documentation.</p>
<p>Documentation should use the easiest to follow, least technical language it can without being inaccurate. It's not an academic paper; it's an explanation to your fellow developer.</p>
</blockquote>