When I started building Syntax & Stories, documentation was the last thing on my mind. I was too busy building features, fixing bugs, and pushing deploys at midnight.

Then I took a two week break from the project.

Coming back was painful. I stared at my own code like a stranger. Why did I write this function this way? What does this API endpoint actually return? Why is there a comment that just says "fix this later"?

I had built something I couldn't fully understand anymore. And I built it alone.

That's when I understood what documentation is really for. It's not for other people. It's for future you.

What documentation actually means

Documentation isn't just a README file. It's everything that helps someone — including yourself — understand your code without having to read every line of it.

It comes in different forms:

Code comments — explain the why, not the what. The code already shows what it does. Comments should explain why you made the decision you made.

python

# We use pessimistic UI here because the like action hits Redis first
# and syncs to Postgres asynchronously. Optimistic UI caused count drift.
def like_post(request, post_id):
    ...

Docstrings — describe what a function does, what it takes, and what it returns.

python

def send_push_notification(user, title, body, url='/'):
    """
    Send a browser push notification to all active subscriptions for a user.
    
    Args:
        user: User instance to notify
        title: Notification title string
        body: Notification body string
        url: URL to open when notification is clicked (default: '/')
    
    Automatically removes expired or invalid subscriptions (410 responses).
    """

README — the front door of your project. Should answer: what is this, how do I run it, and what does it do.

API docs — if you have endpoints, document what they accept and what they return. Future you will thank present you.

The rule I follow now

Write the comment or docstring before you write the function. Describe what it should do in plain English first. Then write the code to match that description.

It sounds backwards. It isn't. It forces you to think clearly about what you're actually building before you build it.

Documentation is a form of respect

Respect for your future self. Respect for anyone who might ever read your code — a collaborator, a code reviewer, or even an interviewer looking at your portfolio.

Undocumented code says "I wrote this and I don't care if you understand it."

Documented code says "I thought carefully about this and I want you to understand it too."

SAS is open for you to write, share, and document your journey. Start with something small — what's a decision you made in your code recently that future you would thank you for explaining?