I understand how uncomfortable and a hassle documentation can be to many developers, honestly, it's boring. But, (clear throat) as a developer, it’s emphatically more than important to have reliable documentation. The reality is, you won't know how important documentation is to a project until you actually need one — then your frustration level rises and breaks the Richter scale.
When I join a new team or I'm assigned a project, I first want to read the documentation about the project, or at least the proposal of the project. Since I will be involved, I need context and to have the big picture of both the problem and the proposed solution (if any), I want to read! This approach among many other benefits, undoubtedly encourages asking reasonable and targeted questions about the project as well as coming up with possible viable solutions.
I use the same practice when it comes to my personal projects. I research and draft an intuitive documentation about what I want to achieve: the initial hows & whys about the project and anything useful that comes to mind is also being captured — even while doing the oddest activities.
I love my job, but I've never been this demotivated as I am now. I just joined a new team, this team have been working on a project since
2013/2014, it's now
2018 people, and no documentation for this project! I'm still trying to see if this is a prank or something. It's a problem, everything is going so slow. I have to move from one developer to the other who took part in this project to explain things to me.
Well, at the moment, my teammates think I ask rather too many questions. Here is the reply I got from a developer after I asked of where I can read about this particular project, "we've all been here since the project was launched and we all know everything about it, so what's the point of the documentation?" The only way one can listen to such a statement and not be incandescent is, you've got to first consider it's the joke of the day; then act like you’ve evolved, breathe and not growl. Nice trick, it works! Dick Brandon said, "when your documentation is good, it is very, very good; and when it is bad, it is better than nothing". In this unfortunate situation, it would have been better to have poor documentation as opposed to zilch.
It Will Cost You Your Time!
If you’ve been following, you can tell a lot about my 9 to 5, most days feel like a waste of time. I think everyone knows the inconvenience of writing documentation, but when it's late, it will cost you a great deal of time; directly proportional to the delay — very painful. In Big O notation, it's
O(N) — no one wants that. Now, imagine how long it will take me and my team to document from scratch, a project that has been going on for four years. I will leave you to have fun doing the math... A lot can be achieved within that time. The resolution to this hapless situation is simple and glorious. Document continuously!
What Do You Document?
Everything! Document the problem you are trying to solve, document the solution, document the technologies, all decisions you make that lead or will lead to the solution need to be documented. Document your server environments, document your business rules, troubleshooting, installation, code, code deployment, etc. Like a Bellevue Linux user group member said: Even the documentation needs documentation... Thank goodness, documentation can be reused.
How To Document
How you document your project can chiefly depend on a few considerations: the project and the audience. Documenting a personal project will be exceptionally different from a public project. Personally, I don't follow a standard when documenting my own projects, I go with what floats my boat: I use a lot of shorthand and code names. But since common sense is objective, I wouldn’t apply the same technique on a corporate project.
Furthermore, documenting for a technical person will as well be different from a non-tech individual. The key is — know your audience. Use whatever works for you, avoid equivocation. Remember, the aim is to guide. You can get started with the beginner's guide to writing documentation.
Like this Chinese Proverb says: The palest ink is better than the best memory. I reckon that it's just sensible to document your projects. Don't expect that you or your teammate will remember everything about a project worked on 2 months ago. The solution is: Documentation! Someday, you will need it, an intern or new hire in your company will too. As Edward Yourdon said, “there is nothing in the programming field more despicable than an undocumented program". Now, this is the truth, I dare you to live it.