Introduction
Article Sections
As a web developer, I rely heavily on documentation when implementing new solutions. When those solutions are very technical like APIs (Application Programming Interfaces), then I really need something that will help me learn how to use the API properly. For some reason, a lot of online documentation is still lacking and incomplete. Sometimes, I need to do something really complicated and complex and the documentation is not detailed enough for me in order to finish what I started. Why is documentation still so incomplete? That is the topic of this article as I delve into the issues I have had with poor documentation.
Why Is Online Documentation So Important?
There are several reasons why having complete documentation available online is crucial. I will go through each one and explain why implementation can spend several days in a stand still because the documentation is not finished. Other alternative solutions include contacting people for support but more often than not, responses can take a long time. There can be a lot of back-and-forth communicating that goes nowhere. Also, responses point back to a lacking documentation that made you contact someone in the first place.
Developers Need to Know How the System Works
I briefly mentioned that developers need to know how systems work. Sometimes I feel that assumptions are being made that we are capable of figuring things out, even if things are not laid out clearly in plain English. There is a lot expected from us. I guess that it comes from the fact that we do something that seems very complex and difficult for some, maybe for many.
We all do something different for a living. I just happen to be a programmer. This is what I do and this is what I am good at. I always think that if I tried to do what someone else does for a living, it would probably be too hard for me because I am already so used to being a web developer for so many years now.
Back to the article, we need to know how the system works. In order for us programmers to do that, we have to understand the ins and outs of the system very, very work. Programming is very exact and precise. It is not something that kind of works, it just works. No gray area here open for interpretation, just black. Like I said, things just work, no questions asked.
This is why we need to know the details of how the system works with very thorough and comprehensive documentation. Without, we have to spend time guessing how things may work but again, we do not operate under a gray area. Is it very black here and we need to know exactly how things work. We need to get the system up and running and done. This is why online documentation is so important
Very Technical Systems Need Very Complete Documentation
To add on from the previous section, the general nature of systems is that they are very very technical. Very technical, very precise, these systems leave no room for error when being built. Due to this, documentation must be complete and devoid of lacking detail, or else we will not be able to accomplish what we started.
If programming were not as intricate and detailed, then documentation does not need to be so complete. The reason why is because programming has to account for every single step that it takes when completing any kind of task. If one step is skipped, then the program will not work properly. This attention to detail is just another reason why complete documentation is important.
Good Documentation Saves Development Time
When documentation is complete, then it can save development time. As mentioned earlier, contacting someone is not always the best course of action because the response takes awhile to receive and does not always answer the question being asked. This can waste a lot of valuable development time as developers struggle to get things done as quickly as possible when they encounter roadblocks.
The Problem With Roadblocks
Roadblocks are common because sometimes developers just get stuck trying to figure an algorithm out. Documentation should be able to resolve this issue because we need to remove the roadblock and continue developing as-soon-as-possible. When roadblocks impede progress for great lengths at a time, then the project is in jeopardy of being delayed. This is a major issue because the due dates are missed and milestones are not delivered on time. This causes people to worry which is why roadblocks need to be resolved as soon as they appear.
With good documentation, roadblocks can be moved out of the way so that development can once again commence.
Less Debugging and Trial-and-Error is Good
When documentation is sufficient, developers spend less time debugging and engaging in trial-and-error testing. If documentation is lacking, then developers have to take it upon themselves to be the documentation that performs endless debugging trying to figure out why something is not working.
We then have to test more often and go through exhaustive trial-and-error just to make sure that everything works. The problem with this, is that it takes a lot of time to test things out when the documentation could have saved us time and just tell us the answer from the beginning.
Less Hunting Online for Answers: Spending Time on Stack Overflow
Speaking of spending a lot of time avoiding roadblocks and debugging, we also spend time looking for answers online. If documentation will not provide us what we seek, then we will have to go elsewhere for answers. One common place that developers go for answers is Stack Overflow. Stack Overflow is a great place where other technical people like myself go to when they need help with some really technical questions. Other developers are probably going to Stack Overflow because the documentation they too are looking for is also sorely lacking.
If we cannot find answers in the documentation, then Stack Overflow it is. If documentation is good, then we would not need to go to Stack Overflow as much. This is why we need good documentation.
Documentation Becomes the Official Single Source of Knowledge
It would be nice if we could just go to one place for everything. Instead of having to start with the documentation and using Stack Overflow to fill the gaps. This would make it better because even Stack Overflow does not know all of the answers. If both the documentation and Stack Overflow do not have the answers, then where do we turn to next? I mentioned earlier that two other sources of answers are ourselves as developers and seeking support through someone else.
See all of these different sources that you have to consult with to get answers. Would it not be great if we could just get all of the answers from the documentation. Solid documentation should have all of the answers.
Online Documentation is Available 24/7
I have hinted at this earlier that documentation is great because it is available all of the time. When you have to contact someone, they can take a while to respond. This is why it is so important to have great documentation because long human response times can cause roadblocks to block your road indefinitely.
So Just Why is Online Document Still Incomplete?
We now know why complete documentation is important and the problems that can be caused without it. Why is that the case? Why is documentation in general still incomplete when it is so crucial? That will be the focus of the next section. We will now take a look at why it is missing so much even though developers need it.
Systems Assume That Developers Can Just Figure It Out
I think that some people think that we are capable of being self-sufficient because they think that we figure anything out. That just comes from not knowing exactly what we do and how we do it. There is a sense of mystery and elusiveness in the air with being a programmer. As I mentioned earlier, the things that we build just work. How? People in general do not know, they just know that it works.
Same thing when you compare building a car versus driving it. Two completely different things. People know how to drive it, but could never build or fix it. Same thing with a website. People know how to use your website, but could never build one at the same complexity. So this is why everything needs good documentation because building something and using it are two different things. We need to be able to build solid products that people can use with good documentation.
Issues Are So Technical That Documentation Cannot Cover Everything
This is just the nature of programming. Development can be so involved and complex that documentation can never cover everything. There are many solutions to solve a problem and documentation would have to cover every single possibility to be considered complete. This might be just expecting too much at this point.
At the very least, we can see if documentation can at least be better than it currently is. How much better to satisfy developers? Very tough call to make here because each developer does things differently and are at different experience levels. So when you consider this, then having documentation catered to every developer is impossible. Rather, we attempt to make documentation more useful to most developers out there.
Providing Complete Documentation is an Ongoing Endeavor
Keeping on that train of thought, documentation just like everything else in life is something that is always happening. This is what keeps documentation incomplete because there are always updates that it needs as systems get updated.
In the next section, I discuss methods that can be used to keep documentation current and useful. If we are going to supply developers with a resource to help them, then it might as well be useful for them.
How Can Online Documentation Become Better?
We understand now how important documentation is and all of the issues that stem from having it incomplete. There are some things that can be done to improve documentation so that it is more useful and reliable.
Keep Document Updated With Version Updates
Active systems are constantly being updated with new features. Often, these brand new features need to be documented beyond a change log. A change log is just a list of changes that were made in the latest version. Brief details are provided but not much else. You are just aware of what changes are made but not necessarily the impact of those changes and how to deal and handle them.
This is why whenever new system versions are released, documentation updates must follow also. If the documentation does not follow suit with new versions, then the document continues to be obsolete and possibly serve very little use to people.
The reason why is that new versions are riddled with bugs and they need to be resolved. Documentation can illuminate these issues and provide possible solutions so that uses are not concerned with updating to the latest version.
Do Not Just List But Define and Explain Functionality
Many documentation merely just list what the system can do and that is all. In order to make documentation better, it should explain functionality in detail. This makes the documentation more reliable because then people will be able to get all of the information that they need from the documentation and not another source. The goal here is to not push people away from the documentation and have the rest of their questions answered elsewhere.
Exhaust Details and Do Not Assume Everyone Understands At the Same Level
Good documentation provides details, but excellent documentation exhausts them. As mentioned earlier, developers who read documentation will have all different levels of experience. Some developers can understand and use documentation with little details. Other developers who are newer will require more details in order to make better use of the documentation.
We try our best to accommodate all kinds of developers because programming is so technical that each developer will have a different background. I am not only talking about years of programming experience. I am also referring to the different skills a programmer has. Each programmer has a different skill set with different languages. The relevancy of the mix and combination of these languages will determine how well a developer will be able to absorb documentation.
Keep Track of Common Issues Found In Community Support Forums
Some documentation has an accompanying online community where people can seek additional help. Ideally, we want people to go to the documentation first before going to the online community. The reason why is because we are trying to get questions answered without human intervention.
If there are common questions that are constantly being asked and answered, they should be integrated into the documentation. Documentation can answer questions faster than people only if they are complete and provide a solution that users can actually implement successfully. It is not just enough to offer a complete answer. Users must be able to take that answer and implement it without requiring any further assistance.
Summary
Online documentation is crucial when it comes to understanding and implementing systems. Documentation is important because developers need to be able to implement without spending too much time debugging and testing. When developers become stuck on something, roadblocks can consume a lot of time and even more if documentation is not sufficient to remove the roadblock.
This means that developers will have to seek out answers in other ways which include support forums like Stack Overflow. Ideally though, documentation is complete and will not require going to a forum. Since documentation is always available online, it can be more reliable than having to wait for responses from a forum. The advantage that forums have is that they can fill in gaps that documentation lacks. Why? The reason is because forum questions can be very specific and unique to a single user and therefore receive very specific responses tailored to that user’s question.
Documentation tends to be incomplete because it is assumed that developers can figure things out without it. This is tough since each developer has a different skill set and levels of experience. Also, the technical nature of programming is one that makes it hard for documentation to cover everything.
Since documentation is incomplete, how can it be improved? Keeping documentation updated with system version releases is a must. This prevents documentation from being obsolete. It is not enough to just list what the system can do but detail it, exhaustively. Also, add common questions and answers asked in forums to documentation.