This is my first post anywhere, so be gentle! :)
Also, this is my opinion based on my work experience and in the type of projects I have encountered. I would love to hear your opinions on the article in the comments!
I know what you're thinking. Everyone hates documenting stuff.
Take for example doing your taxes. I hated doing the taxes until they implemented a mechanism for me to click "Yes, I confirm" and be done with it. But we do taxes because we have to. Documenting is based on the same principle.
Nowadays I've turned a new leaf and I'm actually really fond of documenting. I try to document everything I can, with as much detail as necessary. I believe in teaching my junior team members the same thing. As soon as they enter my team they quickly realize if it's Not Documented, It's Not Done.
Note: Documenting and Commenting are two separate things. Think of code like a problem: while commenting mitigates, documenting fixes.
When I started my first job, the moment we got an email saying that we won a new contract, was also the moment we started writing the code. There is no worse practice than this in software development!
Software development is like building a house. First you study the best approach, you review it, then you get your hands dirty.
This has happened to me more times than I can remember. (Un)Fortunately I'm usually the firefighter who needs to put out some major fires in different types of projects. Maybe that's one of the reasons why I now like to document a lot.
Imagine you are put on a project already on course and you have 3 days to implement a feature without absolutely no context at all. What would you give to see a really good written manual about what the project does, and how does it do it.
Everyone likes starting a project from scratch and just going heads on to the code. Nobody likes entering a mid-finishing project without knowing properly what happened.
Help your local firefighter colleagues and document people! Be it in .md, a word file, or even a Visio that explains the flow of the application you're developing!
I hoped you enjoyed the article!
- What are your feelings on documenting? Do you like it or do you hate it?
- How do you usually document?
- Are you normally the firefighter in you team? :)
Top comments (12)
Good documentation is nice but there are reasons why it rarely exists. This is not just a matter of laziness.
Again, good documentation is really nice. Unfortunately most of the documentation that exists is not too helpful in practice, even when it has been written by intelligent and competent people. We typically think that we can do it better but it is really hard and might not be worth the effort.
Don't get me wrong, this is not meant to be pessimistic. I am describing the current state of affairs and am sure we can do better in the future. But this will not be easy to achieve and cannot be accomplished with a little bit of motivation. It will probably involve tools that automate part of the process.
This is one of the most important points. When you develop, you estimate the effort contemplating the documentation you will have to change. It's basically the same with tests:
Effort For Feature = Documentation Effort + Implementing Effort + Testing Effort
For every Effort you ignore, troubles will arouse, one way or the other :)
Good point, documentation updates need to be planned, otherwise they will probably not happen at all.
But that does not change the fact that they can cause a lot of overhead. A simple feature that is quickly implemented can require many documentation changes in multiple documents. It is far from being trivial to find all the places that need to be modified in natural language documents. Things get worse when you work in a larger team where multiple changes are implemented simultaneously.
There are approaches like ALM (Application Lifecycle Management) that promise to resolve issues like that. But so far I found all ALM systems to be hard to set up and use.
Updating tests is less difficult because a test will tell you that it needs to be updated, simply by failing - assuming that the change is implemented correctly. Unit tests are even less critical because they are closely related to the code that has been modified.
I've worked in places where every problem is met with "we should've documented this better" over and over again. So people document lots of stuff. Problem is it's not challenging the real issues, with the organisation and the code
I'd quit. Documentation is not the long term solution to this kind of madness.
Another example. Team decided we needed to create lots of documentation for the release process, this is not at all uncommon even when you have CI tools. Documentation is not the solution here, a simple release process is.
I'm not against documentation, but its not the panacea it's often seen as.
True, maybe the example was an overkill :)
Often I don't encounter those types of projects, but that doesn't mean they don't exist. But here is where I disagree, Documentation is the solution. You stop doing features and you consolidate the features that already exist by documenting them :)
Normally we set templates for types of CI and CD processes, which we (and normally I) document :b
I love writing documentation. I know that most others don’t, and completely understand. However, that doesn’t mean you just get to avoid it completely. There are various things about our jobs that are hard, but we still have to do them. Documentation should be no different. I can’t stand it when places have 0 documentation and then tell you to “read the code” to figure it out. Cool, I can totally read code. But your code better be damn good and 100% legible. You better have some consistent docs on your functions. If you don’t, your code probably won’t reliably tell your story.
If documentation is an aid to understanding program flow and is non existent, I would propose that the time is better spent cleaning the code base so that the code is the documentation.
Meaningful named variables, classes and functions. Proper encapsulation and good unit test coverage. I.e. the tests are your documentation. Software invevitably changes over time and the documentation will not keep up. But in the absence of clean cidey, yes documentation can help.
I disagree! :)
I actually have a good example that happened to me not long ago. One of my clients had a problem in production with a very old program (like really really old), so my boss wanted me to stop by and try and help them the best way I could under the circumstances.
When I got there, and asked them for documentation on what the project does, test plans to figure out what the project could do, or even a person to talk to. Of course, nothing :)
So we went with the approach you suggest: Clean up code. We couldn't do major changes but we did some.
If you only knew the business rules we broke while changing one line of code... That we could have avoided if we had some sort of documentation. :)
Yeah, I'm with you on this one. And this problem only gets worse when you're working on a large project involving multiple teams and multiple interlocking services. Every time you see a call in the code, there's a chance that it will be to consume a service in some other, equally poorly documented program,and figuring out how it's supposed to work is that much harder.
Now that I work on a company that values documentation, I understand the enormous value that provide. From keeping a journal, to write a spec that will avoid the necessity to explain over and over again the same information to different people. As a developers we tend to look a this tasks as tedious and see no value on them until we face or witness some of its advantages.
Fortunately, I have witnessed those advantages! :)
Documentation is always a challenge. Not only does a team have to overcome the common aversion to writing it (and I hold my hands up as someone who finds writing docs not as fun as writing code), but there is also the struggle to ensure it stays relevant and up-to-date.
In the same way that data redundancy in a software architecture will constantly cause it's maintainers synchronisation headaches, as will syncing documentation of how code works with the code itself.
I have found that most docs relating to how code works in any sort of detail are doomed to quickly go out of date/sync unless they are inline with the code itself. Even with the best will in the world, people inevitably forget that particular docs exist to be updated.
Even if such docs are available and happen to be up to date, if I'm newly coming in to a project, past experience has taught me not to trust such documwntation too much (for the above reasons), and if you really want to be sure how some business logic actually works, you need to read the code.
So am I saying don't bother? No not at all. But I have found the best approach is to write code to be as self documenting as possible. Good naming and layout of code can help alot here. Where more explicit descriptions are needed code comments can be used.
Well written test suites are also a great way to not only ensure code does the right thing, but to describe what that is.
Where documentation outside of the code can be useful is in describing the high level concepts such as the system design and architecture. These have a fighting chance as they change less often and it tends to be a bigger event when they do. For Http APIs, libs that generate specs for tools like Swagger from the code are also very helpful.