“Hello! I am a developer. Here is my relevant experience: I code in Hoobijag and sometimes jabbernocks and of course ABCDE++++ (but never ABCDE+/^+ are you kidding? ha!) and I like working with Shoobababoo and occasionally kleptomitrons. I’ve gotten to work for Company1 doing Shoobaboo-ing code things and that’s what led me to the Snarfus. So, let’s dive in!
When it comes to documentation, at least for myself when I’m learning new things, I like to look at it like a recipe book.
The book shouldn’t contain just the ingredients and what the final product looks like. It needs to be more in depth than that. It needs to contain the ingredients that go into it, how much of those ingredients, the time to cook, what consistency to look for, prep time, etc.
There are plenty of people out there who have never cooked before, and a recipe book/instructions on how to cook a favorite dish is the perfect way to share your love of the craft and the dish that you made. Then, with your recipe as a guideline, people could change it to suit their tastes, and so on and so on.
That’s just how I look at it. I wish I could interpret developer instructions and write up a more user friendly documentation for them. I would love to be able to give back to the community in some more meaningful way than just barely knowing what the developer is providing and using it and making a mess of it my first few tries until I learn from my mistakes.
I structure my tutorial docs (I write a lot of them for work) like the O’Reilly cookbook series for this reason.
The problem you’re trying to solve is at the top. Next comes a list of prerequisites for the instructions. Then clear, step-by-step instructions with no more than one command or action for each one, highlighting anything that’s different depending on environment.
Then at the bottom I’ll sometimes add a discussion of why each command does what it does, and finally a list of resources for whatever programs or systems the instructions are about.
Thank you for that. I’m sure the people who read it and got a grasp of what they are trying to accomplish greatly appreciate your going out of the way like that. :-]
Usually it’s to help a customer create a proof of concept going so we can make a sale so it’s not entirely a selfless act.
Plus it keeps me from sitting on hours-long calls trying to walk them through ambiguous instructions.
These days I pretty much just give the code to the LLM and it spits out documentation
Is it prefect? No. But it takes me literally 10 minutes and it’s 90% there
In being slightly facetious here, I do spend some time on it to make it appropriate. But it sure does a good job imo
This is one of those things where I’m actually okay with AI use. I understand a lot of the FOSS community devs don’t have a lot of time for such matters, so if this gets it at the very least 90% there, I would consider it a win! (human review being a big bonus, of course!) :-]