Keep it simple.
1. Recognize that most people do not like to sit down and grind out documentation. They never will. God bless those who can do it.
2. Recognize that many people do not like to read documentation and will often miss important details anyway.
3. Recognize that many of us would prefer to watch a short video when given preference.
4. Recognize that many of us are social creatures and we prefer talking to each other.
5. Recognize that many people are most confidant when speaking in their conversational voice, and talking about things they actually know.
I facilitate short 1-on-1 recorded sessions with my team. I ask them to talk at length about various aspects of their jobs. Once they get going, they will tell you everything they know, even where the bodies are buried (so to speak)
Attach transcripts to videos (to make it searchable), and title it appropriately.
However, you must come prepared to the call! Have a list of bullet points and questions that you must cover. Fire them off to your devs and collect the responses accordingly. Do not be afraid to go into rabbit holes on specific details.
If you can, get everything into story format. Rather than "just the facts," ask them to tell you the full context. How did we arrive to the curret state of things? What have we used such non-obvious methods of solving this problem?
Doing this does two things:
- It makes it much more engaging for your viewers / readers. They get onboarded into the problem much more easily.
- The story-teller digs into his memory and experience, shedding light and insights that would not otherwise have been revealed simply writing documentation. This is why Barbara Walters, Charlie Rose, and Piers Morgan make the big bucks – they get more out of their guests!
GPT and LLMs lend a hand
This one could be a game-changer, but the jury is still out on it. My strategy has been to feed it my notes, thoughts, and example use cases. I prompt it with instructions and guard rails for what is good output. It usually takes a few iterations, but results are promising.
This one is an interesting use case. It is like having a capable copy-editor on hand who can quickly help bring structure to my loose notes. I find myself wanting to experiment more with other LLMs like llama.