be patient and read all documentation, the answer is always at the
next line :)
Why write documentation?
the overall idea for documentation is to capture information that
was in the mind of the designer but couldn’t be represented in the
code
How to write documentation?
write before implementation
keep in mind the four types of documentation
Tutorial e.g. get started with working code
How-To e.g. Step by Step Guides like Recipes
Explanation e.g. experts deep dive
Reference e.g. function docstring or python official
documentations
starts with executive summary
add order of operations (function calls/rest api calls) to
documentation
inspiration: a network protocol defines the format and the order of
messages exchanged between two or more communicating entities, as well
as the actions taken on the transmission and/or receipt of a message or
other event.
write present tense with full sentence
Read documentations before using a new tool
for new technology, it’s important to understand how to use them
before we use them
understanding a tool also sparks new ideas on how to use this
tool
this implies prefer using tool with good doc e.g. fish
instead bash
python docstring should what Exception can be raised in
feature entry point
such as for entry point function one_fee_calculator,
detail all possible expected exceptions raised in downstream
functions
always write input and output from and to third party API system
calls