This week in my Open Source Development class we were discussing a topic of Documentation.
When (almost) every programmer hears a word "documentation", first thought is pain.
When you start documenting a production-ready project, you know that the next days/weeks are going to be a hell.
It would be nice to start documenting stuff from the beginning, but you didn't... You were too excited with coding and solving more significant(as you think) issues.
I have been there. If you are working on your own the only documentation you might have are comments to explain some hard-to-follow places in your code and maybe that's fine for now. But what if you come back to this project in a few weeks or even months. You will not remember which component does what.
I have a small rule I follow while working on every new project. I try to put meaningful comments, so later on you can reuse a code without spending a long time figuring out what that function does.
I also like to start working on README file as soon as I set up development environment. It's much easier to document things you are currently experiencing, maybe paste some links/commands to download all the dependencies or put a note how to solve an issue and how you overcome it.
Proper documentation would be definitely appreciated by your team, your boss, contributors and even yourself.
So if there is a question: do I need a documentation? The answer is always: "YES!!!", even if that's a small project living on your local machine.
Tips and useful links:
When (almost) every programmer hears a word "documentation", first thought is pain.
When you start documenting a production-ready project, you know that the next days/weeks are going to be a hell.
It would be nice to start documenting stuff from the beginning, but you didn't... You were too excited with coding and solving more significant(as you think) issues.
I have been there. If you are working on your own the only documentation you might have are comments to explain some hard-to-follow places in your code and maybe that's fine for now. But what if you come back to this project in a few weeks or even months. You will not remember which component does what.
I have a small rule I follow while working on every new project. I try to put meaningful comments, so later on you can reuse a code without spending a long time figuring out what that function does.
I also like to start working on README file as soon as I set up development environment. It's much easier to document things you are currently experiencing, maybe paste some links/commands to download all the dependencies or put a note how to solve an issue and how you overcome it.
Proper documentation would be definitely appreciated by your team, your boss, contributors and even yourself.
So if there is a question: do I need a documentation? The answer is always: "YES!!!", even if that's a small project living on your local machine.
Tips and useful links:
- Use this website to get started with Markdown (it stores cookies, if you want to start everything from the scratch again either clean those or access the website in incognito mode)
- Gitlab Markdown cheat sheet
No comments:
Post a Comment