Documentation is never good

 I have a problem. I am never good at doing documentation well. Whenever I troubleshoot a tech ticket that seems odd and there isn't a wide range of google results, I try to document it or even document the network(still in progress). However, when someone tries to follow it, I seem to forget either a screenshot or a step. It does get fixed and overall its fine, it works. This is a skill issue yes, I just have not done enough documentation to ensure I don't miss things. 

The reason I bring this up is that I recently try a github repo. The repo was a good project regarding AI and AI voice. Now the instructions are easy, very easy. We download, unzip and then run a bat file. That was easy and straightforward. Some of the best documentation for this project. Once I ran it, I ran into an issue. There is an option to choose to run via CPU or run GPU. However, anytime I ran it it will give me a console error that it can not find GPU. So I figured, this is a python project it must be looking for the cuda toolkit. No worries, installed and tried again. Nope! Okay read documentation on pytorch. Ah got maybe a too advance cuda tookit, let me get the older version. Still no. Okay, let me look at the code function. It lost me, ask ChatGPT. ChatGPT confirms everything I did okay no help. So I know its something with pytorch. I went ahead and checked the issues for the project. Checked all the open logs and nothing related to this. Why is this an issue. Let me check the closed logs. There it is. It seems there is an issue with the pytorch installation and it required a install of pytorch again different slightly from the requirements file. Did that ran it and it worked. Yayy!!!

Here is my issue, the issue is closed with a solution but the solution is still not implemented into the project, nor is it a least a note in the readme to inform you of the steps until its part of the script. So here is the dilemma, Its an open source project, no guarantee it works and these folks have worked hard to provide this. My issue is why is this issued closed, without adding a note to the readme. I get it again no guarantee, they don't owe me nothing, and all in all, I have a skill issue, but at the minimum, if there is a solution to at least try the project out for the common folk, at minimum put it on the readme. Documentation is not good, and sometimes, feel like this does not apply just to this. Sometimes, documentation is so technical, it could be hard to follow. This is not to say I am great at my own documentation, what I am saying is the idea of reading the documentation as the end all be all is not always easy. If the document says this and gives you an end result of what to expect and you get something else, its not that good at the steps in the middle. Documentation is good for the start and to get what is expected which is great to know when you have it, but terrible at the middle. I don't know how many times, I followed tutorials on system setups, application setups, and all other things that usually fail to provide a piece somewhere of what to expect if you get an error. Google searches sure help from time to time but not always. I wish more places would had a section of expected errors with troubleshooting tech from the community. At the end to say, oh here are some common issues the community has run into, do the following if the following occurs. Someone will say, will you have google, you have the forums, you have the issue tracker. Yes, those are all good places, but you will usually turn off a lot of people once they can't get the solution within 5-10 mins. Leaving some bread crumbs in the documentation side helps to at least encourage more troubleshooting when it comes to common problems. 

With that being said, there was a youtube video I once saw where there was a family that told there kids about a challenge to write instructions on how to make a PB&J sandwich. It was funny, kids were frustrated because they assumed to many things, but it gave good insight on how to write instructions. For me, I think its time for me to get better at documentation, and the tech world needs to write better PB&J sandwich instructions.