Thoughts and brain dumps

Thoughts and brain dumps

By Andy Hawthorne. Words, photos, code and running…

11 Jan 2020

Why Readme Led Documentation Works

Reading time: 3 minute(s) - 600 words

There are loads of software projects out there that lack documentation. Or the right kind of documentation.

There might be an overview. Or a body of docs that go into detail. Details that change but the docs don’t.

Neither help when it comes to your turn to work on the project.

As Tom Preston-Warner pointed out, sitting in the middle of those two is the readme. 

What’s it for?

This bunch of code does something, right? But what problem does it solve?

It’s amazing how much documentation exists that doesn’t make it clear what the primary purpose of the app is.

Writing a readme at the start means you answer the question straight away.

As the project grows you see how the purpose might change. You see it because you knew what it was to start with.

How do you make it work?

It is common for projects to have a lot of moving parts. Developers will appreciate a guide to getting the thing working in their setup.

It’s also worth describing the deployment routine. Especially where there are any complications. 

At this stage we know:

  1. What it’s for
  2. How to get it working in a local dev environment
  3. How to deploy it

There’s nothing worse than spending half a day trying to get something running.

What does what and where?

You’ve described what the app is for. That means you’ve detailed the main components.

Now you need to show how those components work. The best way to do that? A tutorial. 

Developers appreciate a tutorial that explains how to use the code.

When the code is for the company’s product offering clarity is also vital.  It makes the purpose description more important still.

If you understand the problems the project is addressing, the code will make sense. Or, it’s more likely to.

What would you want to read?

I know, sounds obvious, right? But there are no hard and fast rules when it comes to developer docs. 

You need to explain what the app does and how to get it running. After that, you need to explain what you can do with it.

If it’s an API it’s easy. Because it should be easy to see what the API is delivering.

Any dev needing to work on it needs to see how it’s called at the very least. If there are amendments to make that’s enough to drive the new work.

Or you’d hope it is.

Readable code

According to WordPress:

code is poetry.

I’m alright with that.

The point is, clean, readable code with good documentation is a nirvana we don’t seem to hit that often.

Finding the time to refactor code is thus time well spent.

The Agile formula of: make it work, make it right, make it fast is not a bullshit aim.

And it helps you to produce good documentation.

Back to the readme

With all the above in mind, clean code, clear purpose definition, etc. The readme style of docs will work well.

It does bridge the gap between verbose documentation that’s always out of date and no docs at all.

Try it. Create a readme at the start of your project and watch it become essential as your project develops.



comments powered by Disqus