Image without description
  • Jacco Meijer
  • |
  • Mar 12, 2022

Documentation

Documenting a software project is challenging. Here's a few simple guidelines that help a team writing clear documentation.

Software projects

Documenting a software project is challenging. Even for smaller projects this can be hard. Below a few simple guidelines that help a team writing clear documentation.

Just do it

Most important is to get started. Keep it as short as possible.

Complex code

When you find that documentation takes up a lot of time, most probably the code is too complex. Instead of documenting, simplify the code. Consider refactoring into smaller modules.

Clean code

High quality code is clear and documentation can be short.

Why?

Documentation is about communication. It's a chance to tell others about your code.

Where?

Have your documentation as close to the code as possible. Use markdown files and place them in the same folder as the code. Where needed use markdown links to refer to documents located elsewhere.

When are you done?

Ask someone who does not know the code, preferably in your team, to be the judge of that.

Easily missed

These topics are important but are often left out.

  • architectural decissions
  • how your code is structured
  • non trivial methods and method parameters

Other posts

Image without description
  • Jacco Meijer
  • |
  • Mar 21, 2024

UI Library with MDX documentation

Using the simple Render JSX plugin for Esbuild this post shows how to setup a simple UI library.

Image without description
  • Jacco Meijer
  • |
  • Mar 20, 2024

Render JSX plugin for Esbuild

Transform Esbuild generated JSX bundles to HTML pages.

Image without description
  • Jacco Meijer
  • |
  • Mar 19, 2024

Esbuild as a static site generator for MDX

Static site generators gain popularity. This blog is about using Esbuild as a static site generator for MDX.

Image without description
  • Jacco Meijer
  • |
  • Mar 18, 2024

11ty and Github pages

Simplifying the Contentful-Gatsby-Netlfy trio.

Image without description
  • Jacco Meijer
  • |
  • Mar 15, 2024

OWASP and CISSP

OWASP recommendations from the independent information security certification CISSP.

Image without description
  • Jacco Meijer
  • |
  • Jun 30, 2022

NPM7 and @npmcli/arborist

@npmcli/arborist is a powerful library that handles the new NPM 7 workspaces. This blog is about a simple make tool that uses the library.

Image without description
  • Jacco Meijer
  • |
  • May 12, 2022

Comparing React app, Nextjs and Gatsby

A new React project starts with a React toolchain. Main tools in the chains are SSR, React server components and GraphQL.

Image without description
  • Jacco Meijer
  • |
  • May 10, 2022

Versioning strategy for NPM modules

It is important to be able to bump the version of a NPM package without side effects.

Image without description
  • Jacco Meijer
  • |
  • Apr 12, 2022

React component themes and CSS variables

Creating React components with flexible themes by using CSS variables.

Image without description
  • Jacco Meijer
  • |
  • Mar 21, 2022

Content modeling with variants

The efficiency of a variant field in a content model.

Image without description
  • Jacco Meijer
  • |
  • Mar 12, 2022

Documentation

Documenting a software project is challenging. Here's a few simple guidelines that help a team writing clear documentation.

Image without description
  • Jacco Meijer
  • |
  • Mar 11, 2022

Javascript history

In 1986 David Ungar and Randall B. Smith developed Self at Xerox PARC. Inspired by Java, Scheme and Self Brendan Eich created Javascript in 1995.

Image without description
  • Jacco Meijer
  • |
  • Mar 10, 2022

On Javascript transpilers, bundlers and modules

There's Javascript transpilers, modules, bundles and bundlers. This is a brief overview of all of these.

Image without description
  • Jacco Meijer
  • |
  • Feb 11, 2022

Agile Scrum

The Agile Scrum framework is flexible enough to be used in many different ways. Here's one way of working.

Image without description
  • Jacco Meijer
  • |
  • Jan 20, 2022

What happened to Wheelroom?

Founded in 2018. Started to fly in 2020 and abandoned in 2021. What happened?

Image without description
  • Jacco Meijer
  • |
  • Jan 19, 2022

Contentful, Netlify and Gatsby four years later

What did we learn from using Contentful for four years?

Image without description
  • Jacco Meijer
  • |
  • Jan 18, 2022

Typescript interface for React UI components

How to define an interface for React UI components that prevents breaking changes.

Image without description
  • Jacco Meijer
  • |
  • Jan 17, 2022

Naming React components

What's in a name? A clear naming strategy helps developers communicate. Most devs rather spend time writing component code than wasting time on a good component name.