Software documentation almost made me quit

How do you feel about reading some software documentation or some tutorial that you are engaged to master and then you fail miserably in the hello world section? Pretty useless I guess. Now, try to recall when you started a computer science course or just started working on IT and faced that situation over and over and you feel like you are unable to complete any simple task. Ok, I get you. Be cool rookie, or even if you are experienced, you will always face things like that in IT.

I was once in your skin of getting desperate (Still I am several years later :D). Quick story: I started computer science back in 2008 in Universidade Federal de Goiás (Brasil), the dominant programming language out there was Java, and my life wasn’t easier reading Sun documentation when the Java version was at 6, then imagine setting up a web application with Spring and all those XML files. Forget it, this is not a straightforward path, this is a hard journey and I almost quit several times. But I didn’t.

Here I am more than a decade later pretending that I know something. Maybe “I know nothing” like Jon Snow, but I do know you have to keep in mind that software is always evolving, tons of code every single day are going live and people normally left documentation at the bottom of their priority queue (right after testing lol). If you have a job in IT, you can look around to check that by going on to the confluence page of your company and see how poor and outdated are those texts. Other companies out there are just like yours, some have more money some less, but the real problem is common, nobody wants to write it down.

Tips

Even the minor changes on the software may lead you, reader of the documentation, to fail in bootstrapping your application, so the first good tip for you is to not choose the latest version, go for the stable instead. This advice is not a silver bullet, it just may avoid some headache.

However, the best tip I have for you has persistence. Try to make it work for a while, read again the documentation to see if you have missed something. If the problem remains, go to the FAQ or troubleshooting section on the same website to see things related to your problem. Try to understand what happened by reading the logs in the application, do not see that only as a bunch of random information, the logs show us all the stack of execution, step by step, so try to see some error or warning that may give you a clue.

You may be mad at this point for spending half of an hour or more in a dummy sample. You are not dumb, your operating system may be different, compiler with a different version or package manager, or some dependency is not downloading, I can give you a thousand reasons why you may be stuck. Stop having second thoughts about yourself, this is not healthy. Maybe you are dumb anyway, but this is not the reason (just kidding ;)).

Observation: In the Docker age, you face much less problem than before, since companies or anyone can upload some image with all setup you need, and you don’t need to download and install manually anything anymore, besides docker.

Suppose you still need help, then google it and look up websites like Github or StackOverflow. Try to find some topic related to your problem, read all answers and comments to understand the context, and start trying the most voted, then the next one, …

If some of them worked give the feedback by voting up or give thumbs up. Maybe you are in the situation of asking the question on the platform. Then do It. If you did all of this and somehow have succeeded, it’s time to pay it back, so try to find tags and topics related, then it’s time for you to answer and help the community as you build up your reputation in this community. It’s a two-way road.

Ok guys, maybe if none of that has worked so far, we can start thinking about giving up, because things that hard sometimes are not worth it. Ask yourself how someone writes some documentation that doesn’t have the proper support or the community back up?

The last shot is going after your colleagues at college or work and ask for help. Share that on your company group on Slack, Teams, etc. Remember to be clear on your questions by giving the right context to your rescue squad.

Ok, now it’s time to move on, your ex doesn’t want anything with you. Get over it.

You have to judge how much time you have spent on that, if you have another option, if this was really a blocker on your workstream or this was just for fun.

Conclusion

There is no cake recipe when we deal with reading documentation or tutorial, I have given some tips that have worked for me, you can switch the order of steps or skip some and try to find your own way. The important thing is to have persistence and keep in mind that every struggle you have trying to crack your problems will grow you, so getting shortcuts are important in a competitive environment, but be wise when deciding to be quick or take your time to process everything.

Do you have any good tip for reading or even writing documentation or tutorial? Give your comments below, I’d appreciate your feedback.

That’s all folks.