3 ms·

This might be an additional way to quickly iterate on the content of the documentation itself. If I were the one writing, an easy test is passing the documentat

This might be an additional way to quickly iterate on the content of the documentation itself. If I were the one writing, an easy test is passing the documentation to a lay person and asking them if they have what they need to perform X by following the documentation. Perhaps having a focused LLM generate the steps could help catch some documentation deficiencies.

freedomben 2y ago
> If I were the one writing, an easy test is passing the documentation to a lay person and asking them if they have what they need to perform X by following the documentation. What kind of documentation is this though? Is this how to bake a cake or tie a necktie, or is it how to setup a reverse proxy for the services in your k8s cluster? If it's something a lay-person could do then I think this is a good strategy (though depending on the size/scope of the project/documentaiton it does seem like a pretty big effort to undertake without compensation), but if it's something highly technical like Traefik, I expect a lay-person to not even understand half the words/vocabulary in the documentation, let alone be able to perform X by reading it and following it.
- all2 2y ago
  If we push this into the software development domain, my expectation would be something like "documentation should allow a software developer to do this thing without knowing the underlying tooling". > how to setup a reverse proxy for the services in your k8s cluster Going off this specifically. I don't know how to do this. I actually have a k8s cluster on a home server waiting for me to do exactly this. Ideally there would be a doc that would start with ingress selection, and then guide a user through how to get it set up with common use-cases. Or something like that. Like others in this conversation, I've been leveraging LLMs with varying degrees of success to try and navigate this.

freedomben 2y ago

> If I were the one writing, an easy test is passing the documentation to a lay person and asking them if they have what they need to perform X by following the documentation. What kind of documentation is this though? Is this how to bake a cake or tie a necktie, or is it how to setup a reverse proxy for the services in your k8s cluster? If it's something a lay-person could do then I think this is a good strategy (though depending on the size/scope of the project/documentaiton it does seem like a pretty big effort to undertake without compensation), but if it's something highly technical like Traefik, I expect a lay-person to not even understand half the words/vocabulary in the documentation, let alone be able to perform X by reading it and following it.

all2 2y ago
If we push this into the software development domain, my expectation would be something like "documentation should allow a software developer to do this thing without knowing the underlying tooling". > how to setup a reverse proxy for the services in your k8s cluster Going off this specifically. I don't know how to do this. I actually have a k8s cluster on a home server waiting for me to do exactly this. Ideally there would be a doc that would start with ingress selection, and then guide a user through how to get it set up with common use-cases. Or something like that. Like others in this conversation, I've been leveraging LLMs with varying degrees of success to try and navigate this.