Ema Roso

When you have features to build, bugs from months ago to fix, and that one production issue that's been occupying you for the last two weeks, writing documentation feels like time you don't have.

But I've learned that documentation is actually one of the most important parts of the job and should be prioritised.

I've spent way too many hours debugging code built months ago, wasted entire days trying to figure out projects from previous developers who left zero breadcrumbs to follow. I've been the new person on teams where the unofficial onboarding process was "just look at the code".

Even worse, I've spent countless hours digging through forums and documentation for third-party tools, trying to debug issues that turned out to be undocumented legacy bugs. In some cases, it would have been easier to build a custom solution from scratch when you factor in all the time wasted purely because of relying on code that had no proper documentation.

Bad documentation, or lack thereof, is extremely expensive. It costs time, sleep, productivity, and sanity. And honestly, it makes you look like you don't care about the people who come after you or the ones you're working with.

It really doesn't have to be that way. Here's what I've learned about writing documentation that actually helps me (and might help the future you).

Foundation: Assume Your Audience Knows Nothing About It

This one sounds simple, but I have seen so many documentations starting in medias res, including some of my own. Now I imagine I am explaining things to someone familiar with the context but completely clueless about the setup.

Structure: Start With The Basics

I rely on my documentation to answer these main questions in order:

1. What is it? A simple summary that explains the purpose
2. Why does it exist? The problem it solves or the need it fills
3. What do I need to know first? Prerequisites, dependencies, assumptions, background knowledge
4. How do I use it? The basic workflow or main use cases, with examples
5. What are the details? The specifics, edge cases, warnings, known bugs and limitations

This format has served me well, as it covers both the big picture, and the how-tos. Different people learn and understand things differently, this way you will not lose anyone along the way.

Always include any prerequisites and assumptions. Don't make people guess what they need to know. If your tool requires Docker, say so. If it assumes knowledge of REST APIs, mention that.

Organization: Separation of Concerns

The entirety of your documentation doesn't have to live in a single file. If you think of it like code architecture, each piece should have a clear purpose and responsibility.

It might help to break down your documentation into smaller modules that are easier to digest, and maintain.

Some essential sections to consider:

• Overview What it does, why it exists
• Quick Start Get it up and running in the most common scenario
• How-To Guides Instructions for tasks
• Technical Details Explanations of how things work internally
• API References Endpoints, parameters, responses
• Troubleshooting & FAQs Common problems and solutions
• Architecture How everything fits together

Always remember to link everything together. Create a directory of connected documents that guide people through your system. Include links to:

• Related internal documentation
• External tools and libraries used
• GitHub issues
• Stack Overflow answers
• Official documentation for any third-party services

DO NOT document external dependencies.Just explain how you use them and link to the official docs. Your documentation should be compact and focused on what is unique to your environment.

Beyond Words: Making Documentation Accessible

We already mentioned how people learn differently when it comes to structure and organization. Where it also matters is in the format and presentation of your content. Ideally, your documentation goes beyond just use of words.

Code examples. Don't just show the function, show it in use. Include the imports, the setup, the expected output. Even better, make your examples easy to copy and run.

Screenshots and recordings. A 30-second screen recording of your setup process can save hours of back-and-forth questions for users, and yourself. Screenshots of outputs can also be very helpful to verify if on the right track.

Diagrams and flowcharts. This one is my personal favorite. Sometimes a simple diagram explains architecture better than paragraphs of text. Even a simple hand-drawn sketch can clarify complex relationships with ease.

Templates and starters. Instead of describing the ideal configuration, offer it as a template. This gives a working starting point anyone can modify rather than build from scratch.

Outputs and error messages. Show what success looks like and what common errors look like. When someone sees an error, they should be able to quickly identify if it's expected or not.

Reality Check: Traps I Keep Falling Into

Even after writing many different documentations, I still catch myself checking for and correcting these mistakes:

1. I assume people know what I know. I'll use internal terminology without explaining it first. Always define acronyms and domain-specific terms on first use. Create a documentation-specific glossary if necessary
2. I skip the sad path. I document the perfect scenario but forget to mention what happens when things go wrong. Always include error cases and recovery steps.
3. I don't explain the "why". I show how to do something but forget to explain why it's necessary. Context helps.
4. I don't test my own instructions. I write steps from memory instead of actually following them. Always test your documentation.
5. Perfectionism paralysis. I delay publishing until it's comprehensive and complete enough. Meanwhile, people are struggling without having answers to the most basic questions. Basic documentation is better than perfect.

My Template

Here is my structure that you can use and adapt to your own.

                                        
# Project Name

Simple description that explains what this does and why it matters

## What is it?

Answers to:
- What does the project do?
- Who should use it and when?
- What problems does it solve?

## Prerequisites

Before you start, make sure you have:
- **XYZ** (v2 or higher)
- Basic knowledge of [...]
- Access to [...]

## Quick Start

Simple, most basic instructions to get it up and running.

### Clone the repository
    git clone https://github.com/username/project-name.git
    cd project-name

### Install dependencies
    npm install

### Start the development server
    npm run dev

### Visit http://localhost:8080

You should see [...].

## Installation & Setup

### Development Environment

#### Clone and install dependencies
    git clone https://github.com/username/project-name.git
    cd project-name
    npm install

#### Set up environment variables
    cp .env.example .env
    # Edit .env with your configurations

#### Run the application
    npm run dev

### Deployment
[Link to deployment guide]

## Usage examples

### Basic Usage
    const example = new ExampleClass();
    example.doSomething();
    // Output: [...]

### Advanced Examples
    const config = {
        option1: 'value',
        option2: true,
        option3: 2
    };
    
    const example = new ExampleClass(config);
    const result = example.complexOperation();
    console.log(result);
    // Output: [...]

## Technical Details
Explanation of how the project works internally, or link to a separate documentation.

## Architecture
Overview of how components fit together, or link to architecture documentation.

## How-To Guides
    - [Link to task guides]
    - [Link to configurations]
    - [Link to examples]

## Troubleshooting

### Common Issues

#### Error: "..."
Check if [...]
Verify your [...]

#### Slow Performance
Try [...]
Check if [...]

#### Getting Help
- Link to the FAQ
- GitHub issues
- Link to forum 

## Links & Resources
- Link to API References
- Link to third-party Documentation

                                        
                                    

Bottom Line

You need documentation, and it will save you time. I've learned this the hard way.

It doesn't have to be perfect, or comprehensive and complete. Having basic answers to the most common questions is far better than having nothing at all, or something so complex nobody uses it. Any documentation will help you and others.

Start simple, answer basic questions, let it grow naturally over time.

When it comes to software development, code reviews are critical. They contribute significantly to the quality and maintainability of the code. If done right, code reviews can help catch bugs, improve code readability, promote best practices, and encourage knowledge sharing within the team.

Let’s go over some practical tips and steps to make your code reviews as successful as possible.

Set Clear Goals

Before jumping into a review, it is important to have a clear purpose. That means figuring out what you wish to achieve beforehand, whether it's catching bugs, encouraging teamwork and knowledge sharing, or simply making sure that the code follows your coding standards. This will provide direction for both the author and the reviewer, and help everyone focus on specific targets.

Embrace Automation

Rely on tools like linters and formatters to catch mistakes and organise the code, allowing reviewers to concentrate on more complex parts of the review. This not only saves time but also ensures a thorough review, making sure everything fits together smoothly.

Follow a Defined Coding Style

To streamline the review process even further and create alignment within the team, follow a consistent coding style. By setting clear guidelines for style, formatting, and best practices, we are encouraging clarity, improving code readability, and simplifying maintenance, while also making it easier to spot any deviations.

Break Down the Code

For a more effective code review, dividing changes into smaller pull requests can be very handy. This can improve focus, reduce bugs, and enhance code readability, while also speeding up receiving feedback and allowing team members to review specific areas of interest.

Address Critical Issues Quickly

Not all issues are equally important. It is crucial to learn to identify and prioritise those that have the biggest impact. By focusing on critical matters like overall quality, performance, or security, we are making sure that essential aspects of the code are swiftly resolved.

Balance Speed and Quality

To maintain efficiency and prevent delays, focus on quick reviews and consider applying deadlines. Find a good balance between speed and thoroughness, as rushing may lead to mistakes. Adjust review times to the size and complexity of changes to ensure both speed and precision.

Create a Positive and Constructive Atmosphere

Prioritise improving the code rather than criticising the person who wrote it. Encourage constructive feedback with specific examples and improvement suggestions. By explaining our reasoning, we are able to create many learning opportunities. So let’s aim for clear, kind, and specific feedback.

Encourage Self-Review

Approach every code review as an opportunity to grow. If issues are brought up, encourage discussing them openly and collaboratively. By using the feedback received to learn from past mistakes and fuelling continuous improvement, we enhance the overall development process.

Share and Track

Boost knowledge sharing and keep track of important changes and details by encouraging open discussions, rotating reviewers, and documenting the process. This will not only lead to fresh insights and fixes, but also help avoid stagnation and blind spots.

Follow Up

After feedback is given, it should be addressed and necessary changes should be applied before resubmitting the code for another round of review. Remember to follow up on previous comments to make sure that feedback was implemented and responded to properly.

By using these steps, you can change code reviews from just a routine into a way to improve your code, and team. Set clear goals, use automation, follow coding rules, split up code into smaller parts, and keep things positive to make sure that reviews help everyone involved grow. Welcome the chance to learn, get better with each review, and watch your code become stronger and better than ever over time.

Happy reviewing!

Writing clean and maintainable code is not only highly recommended but also a fundamental skill for any developer. Clean code has a great many advantages, including increased readability, simplifying the debugging and refactoring process and enhancing the code. In this post, we will go over some of the of principles and tips for creating clean and maintainable code.

Using Clear and Descriptive Names

When you are naming variables, functions, classes, and other elements, selecting clear and meaningful names is one of the crucial aspects for writing clean code. The chosen names should accurately and clearly convey their purpose and intent. Avoid using single-letter names or cryptic abbreviations.

Let's illustrate this with examples.

                                        
// Unclear naming 

let x = 10;

function f(a, b)
{
    return a + b;
}


// Clear and descriptive naming

let numberOfNewCustomers = 10;

function addNumbers(num1, num2)
{
    return num1 + num2;
}
                                        
                                    

In the first example, the naming conventions used do not provide any description of the variables' and functions' purposes. This reduces readability and makes it very difficult to maintain the code over time, especially as the codebase expands or when other collaborators become involved.

Being Consistent in Your Coding Style

Sticking to a consistent coding style makes maintaining your code much easier. Some of the ways to achieve this are to follow the rules and formatting guidelines of the language used, as well as to use tools like linters and formatters that help keep your codebase organised.

Simplifying Your Code

To make the code more clear, simplify testing, and promote reusability, you can break it down into smaller, more compact units, each with a specific and singular purpose.

Here is a short example to demonstrate how by removing unnecessary lines.

                                        
// While this may be straightforward
// and more efficient for very small codebases

function calculateRectangleArea(rectangleWidth, rectangleHeight) 
{
    return rectangleWidth * rectangleHeight;
}
       
// Breaking it down makes the codebase more readable and reuseable

function multiply(num1, num2) 
{
    return num1 * num2;
}
  
const rectangleArea = multiply(rectangleWidth, rectangleHeight);
                                        
                                    

Using Clear and Effective Commenting

Even with clean and self-explanatory code, there are occasions when comments are necessary to explain more complex logic, provide context, or transfer knowledge. When leaving comments, make sure they are clear, to the point and insightful to future developers.

                                        
// Vague comment with lack of context

// TODO: Fix later
function functionName(param)
{
    ...
}

// Better approach with a description of the issue

// BUG: This function does not handle the parameter correctly. Refer to XYZ for more details.
function functionName(param)
{
    // ...
}
                                        
                                    

Organising Your Code

Approach organising your code in a simple, methodical way by creating well-defined directory structures and naming conventions. Arrange your functions and classes in a careful manner, avoiding functions which are too long, or deeply nested code.

Using Version Control and Commit Messages

By using Git or similar tools and writing clear commit messages that explain the reason behind changes, you can keep a detailed record of all code modifications. Adopting this habit will make it easier to understand in what ways your code has evolved over time and why.

Refactoring regularly

Make refactoring a regular, integral part of your development process. When requirements change, tidy up and organise your code to maintain its usability. Always make sure to update your code as necessary.

Documentation, documentation, documentation

Make sure that a thorough documentation is created for your code, with consideration for both your team and outside collaborators, as necessary. This could include creating API documentation, providing practical examples, and offering clear explanations of important concepts.

Encouraging Code Reviews and Collaborations

Having a culture of giving and receiving code reviews within the team can help detect issues, ensure that coding standards are followed, and promote knowledge sharing. This is where innovation and excellence can thrive.

To recap, writing clean and maintainable code is more than just adopting a coding style. It is a mindset and a commitment to creating code that stays strong, readable and flexible. Following these practices not only improves the quality of your code but also encourages teamwork and makes future maintenance easier.