Documentation

Readability is a primary focus for Python developers, in both project and code documentation. The best practices described in this section can save both you and others a lot of time.

Reading Documentation

I realized that one of the top skills of 10x Developers is to be really fast at reading documentation. Because documentation is the second closest source of Truth (though it can be wrong if badly maintained) after the code itself.

Writing Daily Logs

Writing the logs is actually so good, because everything is written down, so if I already thought about this issue, I can just search it within this single page.

I’ve started doing this since the F1TENTH Logs.

Day-to-Day Documentation

Writing good documentation is the same as writing good code. So that 6 months down the line, when you revisit the project, when you forget why you made those design choices, you have it written down.

And when it comes to debugging things, running code, setting up things, if you document down what you’ve tried, then the process is repeatable.

Thoughts on documenting projects

I’m really going to focus on writing better Documentation. I think I about writing documentation in terms of writing at different levels of Abstraction:

1. YouTube so users can see that it works (AHA moment!)
2. Project page on Personal Website: showcase to recruiters and engineers the amount of thought that goes into your project. See Clayton’s’ page. Give high level intuition of design decisions. Big Crete is also gonna be so cool.
3. (OPTIONAL) Medium/personal website for posting supplementary materials such as tutorials / more documentation on the project so people can duplicate it
4. GitHub (more of a getting started guide?): The Source of Truth. Have a really good README.md so people can run my code in < 30 minutes (that’s including installation time). Look at the f1tenth_gym_ros and f1tenth_gym. If you want to go an extra step, check out https://f1tenth-gym.readthedocs.io/en/main/?
   • There’s also maybe https://atsushisakai.github.io/PythonRobotics/

All of these are made to serve for others to learn more about your project and replicate it. I think all of these things can be written after the fact the the project is finished, because there are so many changing variables on the day-to-day.

So day-to-day has a slightly different purpose: it’s your changelog. Think of like doing git commits, but git commits are so annoying to revert.

• These will have details on design decisions

But really, you should write for yourself. And those things should not be written after the fact.

And when it comes to debugging things, running code, setting up things, if you document down everything you’re doing, then the process is repeatable.

• Show evidence of it not working

So based on the above goals, below is my recommendations.

GENIUS Tip, inspiration from Brian Machado

Instead of trying something first and then documenting it, you should first document the steps you are going to try, AND THEN try it. This is sort of Documentation-Driven Development (…? except usually DDD is about documenting first the features you want to see).

• Because if you try the steps first and then document, you need the remember the steps… and then this can be annoying

When you run into a build error, you write down what you think is the issue, and then try it. This ensures that what you do, the way you resolve an issue is REPEATABLE for others.

Does writing documentation slow you down

What about the idea of Less Planning More Doing? I think writing documentation is part of the doing.

Example

When you first tried running slam_toolbox, write down exactly the commands you are trying. If you are following another person’s guide to a tea, you can maybe just link, but that page might change without you noticing it.

I think i did that well for like setting up PySpark in pycharm, but I had to repeat the process, instead of documenting.

If you are trying to move fast, doing the documentation slows you down a LOT. Because you need to do double the work. But it really pays off in the long run. Like really. For anything.

If you have code to look back on. And also, people can look at your progress. This is how you become a 10x Developer.

Documentation-Driven Development

https://gist.github.com/zsup/9434452

This seems like a good lecture: https://www.youtube.com/watch?v=z3fRu9pkuXE&ab_channel=IgorStarikov

• But more about for writing libraries

They break it down into 4 types of documentation:

1. Tutorials
2. Topic Guides
3. Reference
4. Troubleshooting

For example, from the Django documentation website

• Tutorials take you by the hand through a series of steps to create a web application. Start here if you’re new to Django or web application development. Also look at the “First steps”.
• Topic guides discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
• Reference guides contain technical reference for APIs and other aspects of Django’s machinery. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
• How-to guides are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how Django works.

In my case, the tutorial is probably optional?

Writing Documentation vs. Blog?

I think they serve different purposes, right. Documentation is really nitty gritty, and showcases. Usually, when I think of blog, I think of a tutorial, where I teach a noob how to do things.

But with documentation, I am super diligent with the details. I don’t try to boil down what I’m saying.

Coding Documentation

Use the NumPy style docstring. Example:

def random_number_generator(arg1, arg2):
    """
    Summary line.
 
    Extended description of function.
 
    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2
 
    Returns
    -------
    int
        Description of return value
 
    """
    return 42

Related

• MY Programming Style Guide