Without documentation, software is just a black box. And black boxes aren’t anywhere near as useful as they could be because their inner workings are hidden from those who need them in the open.
You’ve probably seen documentation before, but if you need a refresher, here’s an example from Slack‘s API:
As you can see, Slack explains everything about its API in excruciating detail. Any related pages are linked, there’s a sidebar with easy-to-access topics, and screenshots of what the user can expect to see.
To explain this in more detail, we will cover the following topics in this Process Street post:
Let’s get started.
“Documentation in software engineering is the umbrella term that encompasses all written documents and materials dealing with a software product’s development and use” – Prototype.io, Software Documentation Types and Best Practices
All pieces of software should have some form of documentation that explains, in detail, what the product is, how it works, and why it works that way.
“If it isn’t documented, it doesn’t exist” – Sitepoint, A Guide to Writing Your First Software Documentation
As a developer, your main aim is to write the best code you possibly can. You want your code to be best in class, easy to read, easy to use, and you want great things to happen as a result of it. Right?
But without documenting what you’ve done and why you’ve done it:
No one else can use your code but you
Without documentation, no one will understand what you’ve done and why you’ve done it. It’ll be incredibly difficult, nigh-on impossible, for someone else to pick up your code and work on it. They might even scrap it and start again, as, in some cases that would be quicker than trying to work out what you’ve done and why.
You can’t update or improve it
Can you remember what you ate for dinner on Saturday, three months ago? Unless you’re a complete creature of habit, chances are you can’t. So it’s fair to say you probably won’t remember the code you wrote, two, three, four months after you did it. If you can’t remember the reasons behind your coding decisions, then you will struggle to be able to update or improve it.
Despite this, software documentation is often a task that gets rushed, done badly, deprioritized, or totally forgotten about.
Before we start talking about what tools you can use to write software documentation, we need to think of a way to make sure the task gets done in the first place.
This is where Process Street can help.
Process Street is a piece of business process management (BPM) software that can be used to create, manage, and follow processes.
More about what Process Street is later, for now, let me show you howContinue reading