August the month of creating new habits
Yet another month has passed. Have you been keeping up to date with your reading? Making time to self learn has never been easy when youre in the midst of doing your own startup. But it is these habits that brings you to the next level.
Think about it, whatever you were got you to this current state you are in. If you want to get to the next level (measured by revenue or user conversions), you cannot be at the same level anymore.
Intentionality, Provides history,
Street car in Bay Area
Its done by Chris Arvin, a product designer that seems to give a shit about his own work
Work when you do not feel like it
Writing down everything you know about the subject, no matter how insignificant or obvious. Doing this, you can make those limit concrete, visible, tangible, more obvious.
Break down your knowledge as much as possible. Organize these knowledge into logical manner. Make links between ideas and concepts. Using the Zettelkasten method.
- Thinking in Systems, by Donnella Meadows
- Advanced Web Application Architecture, by Matthias Noback
- Domain Driven Design, by Eric Evans
- Refactoring, by Martin Fowler
- Continuous Delivery Pipeline, by Dave FarleyAccelerate, by Nicole Forsgren, PhD, Jez - Humble, and Gene Kim
- source code comments,
- function names
- active maintainer
Writing excellent documentation is all about keeping the users out of the source code by providing instructions sufficient to enjoy the wonderful abstractions that your module brings.
Who is it written for?
It is expected to have a readme.md in every module that is created. Just as how Github by default loads readme.md on their home page, people are expecting this file to be present. If you want people to understand what you do, create readme file. That is the alignment between creators and users.
This file is written in modules because it is a file related to the module. Whatever that you want a user to know about this module’s utility, put it into this file.
What they do
Your job is to
- tell them what it is (with context)
- show them what it looks like in action
- show them how they use it
- tell them any other relevant details
The lack of a README is a powerful red flag, but even a lengthy README is not indicative of there being high quality. The ideal README is as short as it can be without being any shorter. Detailed documentation is good – make separate pages for it! – but keep your README succinct.
Your documentation is complete when someone can use your module without ever having to look at its code. This is very important. This makes it possible for you to separate your module’s documented interface from its internal implementation (guts). This is good because it means that you are free to change the module’s internals as long as the interface remains the same.
Remember: the documentation, not the code, defines what a module does. – Ken Williams
What does it need to contain?
These elements are expected across all modules regardless of language, so don’t surprise your module consumers:
- Name – self-explanatory names are best. collide-2d-aabb-aabb sounds promising, though it assumes I know what an “aabb” is. If the name sounds too vague or unrelated, it may be a signal to move on.
- One-liner – having a one-liner that describes the module is useful for getting an idea of what the module does in slightly greater detail. collide-2d-aabb-aabb says itDetermines whether a moving axis-aligned bounding box (AABB) collides with other AABBs.Awesome: it defines what an AABB is, and what the module does. Now to gauge how well it’d fit into my code:
- Usage – rather than starting to delve into the API docs, it’d be great to see what the module looks like in action. I can quickly determine whether the example JS fits the desired style and problem. People have lots of opinions on things like promises/callbacks and ES6. If it does fit the bill, then I can proceed to greater detail.
- API – the name, description, and usage of this module all sound appealing to me. I’m very likely to use this module at this point. I just need to scan the API to make sure it does exactly what I need and that it will integrate easily into my codebase. The API section ought to detail the module’s objects and functions, their signatures, return types, callbacks, and events in detail. Types should be included where they aren’t obvious. Caveats should be made clear.
- Installation – if I’ve read this far down, then I’m sold on trying out the module. If there are nonstandard installation notes, here’s where they’d go, but even if it’s just a regular npm install, I’d like to see that mentioned, too. New users start using Node all the time, so having a link to npmjs.org and an install command provides them the resources to figure out how Node modules work.
- License – most modules put this at the very bottom, but this might actually be better to have higher up; you’re likely to exclude a module VERY quickly if it has a license incompatible with your work. I generally stick to the MIT/BSD/X11/ISC flavours. If you have a non-permissive license, stick it at the very top of the module to prevent any confusion.
Why are they crucial
How to craft them well
Bonus: other good practices
Outside of the key points of the article, there are other practices you can follow (or not follow) to raise your README’s quality bar even further and maximize its usefulness to others:
- Consider including a Background section if your module depends on important but not widely known abstractions or other ecosystems. The function of bisecting-between is not immediately obvious from its name, so it has a detailed Background section to define and link to the big concepts and abstractions one needs to understand to use and grok it. This is also a great place to explain the module’s motivation if similar modules already exist on npm.
- Aggressively linkify! If you talk about other modules, ideas, or people, make that reference text a link so that visitors can more easily grok your module and the ideas it builds on. Few modules exist in a vacuum: all work comes from other work, so it pays to help users follow your module’s history and inspiration.
- Include information on types of arguments and return parameters if it’s not obvious. Prefer convention wherever possible (cb probably means callback function, num probably means a Number, etc.).
- Include the example code in Usage as a file in your repo – maybe as example.js. It’s great to have README code that users can actually run if they clone the repository.
- Be judicious in your use of badges. They’re easy to abuse. They can also be a breeding ground for bikeshedding and endless debate. They add visual noise to your README and generally only function if the user is reading your Markdown in a browser online, since the images are often hosted elsewhere on the internet. For each badge, consider: “what real value is this badge providing to the typical viewer of this README?” Do you have a CI badge to show build/test status? This signal would better reach important parties by emailing maintainers or automatically creating an issue. Always consider the audience of the data in your README and ask yourself if there’s a flow for that data that can better reach its intended audience.
- API formatting is highly bikesheddable. Use whatever format you think is clearest, but make sure your format expresses important subtleties:a. which parameters are optional, and their defaultsb. type information, where it is not obvious from conventionc. for opts object parameters, all keys and values that are acceptedd. don’t shy away from providing a tiny example of an API function’s use if it is not obvious or fully covered in the Usage section. However, this can also be a strong signal that the function is too complex and needs to be refactored, broken into smaller functions, or removed altogethere. aggressively linkify specialized terminology! In markdown you can keep footnotes at the bottom of your document, so referring to them several times throughout becomes cheap. Some of my personal preferences on API formatting can be found here
- If your module is a small collection of stateless functions, having a Usage section as a Node REPL session of function calls and results might communicate usage more clearly than a source code file to run.
- If your module provides a CLI (command line interface) instead of (or in addition to) a programmatic API, show usage examples as command invocations and their output. If you create or modify a file, cat it to demonstrate the change before and after.
- Don’t forget to use package.json keywords to direct module spelunkers to your doorstep.
- The more you change your API, the more work you need to exert updating documentation – the implication here is that you should keep your APIs small and concretely defined early on. Requirements change over time, but instead of front-loading assumptions into the APIs of your modules, load them up one level of abstraction: the module set itself. If the requirements do change and ‘do-one-concrete-thing’ no longer makes sense, then simply write a new module that does the thing you need. The ‘do-one-concrete-thing’ module remains a valid and valuable model for the npm ecosystem, and your course correction cost you nothing but a simple substitution of one module for another.
- Finally, please remember that your version control repository and its embedded README will outlive your repository host and any of the things you hyperlink to – especially images – so inline anything that is essential to future users grokking your work.
Checklist for us to check:
Bonus: The README Checklist
A helpful checklist to gauge how your README is coming along:
- One-liner explaining the purpose of the module
- Necessary background context & links
- Potentially unfamiliar terms link to informative sources
- Clear, runnable example of usage
- Installation instructions
- Extensive API documentation
- Performs cognitive funneling
- Caveats and limitations mentioned up-front
- Doesn’t rely on images to relay critical information