Building docs like a product(emschwartz.me)
emschwartz.me
Building docs like a product
https://emschwartz.me/building-docs-like-a-product/
8 comments
I really like that you used the live code components inside the documentation pages. The biggest problem we have in this industry is that the manual becomes wrong as soon as we update the software. If the documentation runs on the same code as the app then it will never be out of date. This is the only reliable way to keep the instructions accurate over time.
I like the interactivity, some of the ideas are nice and I do agree that it's nice when docs are something more than giant walls of text. However...
I think mixing docs and user data is fundamentally a UX mistake. Having interactive components that showcase a behaviour is nice, having them actually toggle some settings less so. Permanently altering the state of the application discourages experimentation, and many users might not even realise that the changes are permanent.
Additionally, a documentation should be designed as to reduce as much external noise as possible, allowing the reader to focus on the things that actually matter. I feel like introducing real-world data can end up being too distracting.
Personally I don't feel like your application warrants a documentation (and don't get me wrong, I'm the first that spends hours overengineering stuff) and I guess that the interactive stuff makes it feel even less so. If I haven't known beforehand I would've guessed the pages to be just another (slightly busy) section of the app. (and whether that's good is for you to decide)
I think mixing docs and user data is fundamentally a UX mistake. Having interactive components that showcase a behaviour is nice, having them actually toggle some settings less so. Permanently altering the state of the application discourages experimentation, and many users might not even realise that the changes are permanent.
Additionally, a documentation should be designed as to reduce as much external noise as possible, allowing the reader to focus on the things that actually matter. I feel like introducing real-world data can end up being too distracting.
Personally I don't feel like your application warrants a documentation (and don't get me wrong, I'm the first that spends hours overengineering stuff) and I guess that the interactive stuff makes it feel even less so. If I haven't known beforehand I would've guessed the pages to be just another (slightly busy) section of the app. (and whether that's good is for you to decide)
I love writing documentation, and I love teaching people how to solve problems. At my day job I've written a lot of the organization's most trafficked explanations and how-to guides for understanding our codebase and engineering principles.
The other week an engineer in another group fed all of my documents, and all of our codebase, into an LLM. They were able to ask it questions, and get immediate answers that were by and large better than the guidance I would have been able to provide in between my other responsibilities.
As much as I love writing and explaining, I think we're sadly past the point that it needs to be done by humans. I have always considered documentation to be an imperfect, point in time, reflection of a codebase. When an LLM can read and synthesize all of code and immediately respond with up to date information... what's the point in writing documentation anymore?
The other week an engineer in another group fed all of my documents, and all of our codebase, into an LLM. They were able to ask it questions, and get immediate answers that were by and large better than the guidance I would have been able to provide in between my other responsibilities.
As much as I love writing and explaining, I think we're sadly past the point that it needs to be done by humans. I have always considered documentation to be an imperfect, point in time, reflection of a codebase. When an LLM can read and synthesize all of code and immediately respond with up to date information... what's the point in writing documentation anymore?
I've read at least 8 articles this week about LLMs having massive hallucinations/brain-farts when writing testbeds for code. Unfortunately, the author didn't see the problems until he tried adding a test; then he had a huge WTF moment.
The fact that the LLM you mention gave good answers is probably more a reflection of YOUR documentation than any particular "brilliance" on the LLM's part.
The fact that the LLM you mention gave good answers is probably more a reflection of YOUR documentation than any particular "brilliance" on the LLM's part.
I love this approach. Great work. Building helpful, accurate has been the second hardest part of building my employer’s internal app. (The most difficult thing has been reaching consensus on processes.)
This is like building a custom swagger implementation
Developer here, happy to answer any questions you might have about Scour!
Also, feedback on the product or the docs is very welcome!
Also, feedback on the product or the docs is very welcome!
Just copy what Mozilla did for MDN.