Hi there, Who doesn't like to write documentation as a developer ๐. As a developer, code, tools and my application performance is the what matters to me, I always think documentation is only necessary at the large company as a part of obligation.
Underrated Documentation
Abandoning documentation is common for beginner developer for a various different reason, there is something in common when I discuss it with my peers. It happen because we:
- Work on assignment project that will be dispose once our scoring done
- Work on personal project which the sole contributor are us
- Think our memory is good enough to remember everything
It's not only happen because of developer, sometimes company need to dispose all "unnecessary" task to shorten business delivery time, and think it can be work on after the business is "settled" (Which for most cases it will not happen ๐).
While it's true we can still work on documentation at later time, but as a time go๏ผ it become unpaid developer debt.
Why Documentation Important ?
Here is my story that make me work on documentation even though I still don't like it ๐ค.
I've been working on certain project for around 6 month, and recently we got a new developer, and i'm in charge to onboard them. At first, I can answer the basic questions like "What language did we use?", "What's our development stack" or "How to clone and run our project locally ?"
The problem arise when the new joiner ask me something specific "How is the data flow from A service to B service?" and "How we handle it from FE side, if specific case happen? ". Keep in mind that i'm not the only developer in this project and we have 0 documentation to be refer to. So I need to gather the whole team and we spent at least 1 week to just make sure every new joiner (and the old pals) understood our whole project data flow and architecture ๐ฎโ๐จ.
Doesn't it better if we have documented everything and when there is someone new joining, we could just send them the document ? at worst we only need to sacrifice 1 person time to help the onboarding, rather than the whole team ๐ฑ.
So here is why documentation is important to me:
To centralize the knowledge of whole team
When i'm the only one working on feature A, it most likely the others teammate doesn't know the implementation detail. If in the near future they need to improve or refactor this A feature they need to ask me, to prevent this to happen i could just made a documentation that everyone can read.
To retain the project knowledge even if someone leaving
People came and go, but the knowledge must retain. Ever heard "don't touch the legacy code" ? yep, it happen because the one made it have left the organization. if there is a good documentation anyone can tweak or do improvement on the legacy code (or not legacy at all since we understood them ๐)
Feature improvement or bug fixing
As our project scale, we can't always remember on what we've done, once the bug occur we need to re-read all of our own code and try to make sense on what it done ๐ตโ๐ซ. It's better if it's documented, even the others can work on it.
What to documented ?
There is a lot of documentation from Class, Flow, or even API documentation. but what should I make all of it ? the answer is actually depends on our situation ๐ค. If you have any thought please leave it in discussion ๐ cause it might help me and everyone who's struggling with this.
From my case this is what our team decide to documented:
- API documentation (using swagger, but make it as detail as possible)
- Architecture Documentation (How our service connected with each other, database connection and any 3rd party)
- Activity Diagram (for each feature)
- Additional Documentation (ranging from configuration needed to custom tools tutorial)
Conclusion
My story might not be the best, but the point is to encourage everyone to start the habit of documenting, even a Markdown documentation or documenting certain feature is great ๐, at least we have a knowledge that we preserve for us and the others โจ.
It might seems to waste our time when we first write it, but it save time when someone need the knowledge, we could just send them over ๐.
Top comments (0)