5 ms·
It might be a hot take, but I think documentation is mostly obsolete. Nobody wants to write it, and nobody wants to read it. How the future works is probably:
by madsbuch 3y ago
It might be a hot take, but I think documentation is mostly obsolete. Nobody wants to write it, and nobody wants to read it.
How the future works is probably:
1. Tutorials / case specific guides
2. documentation-annotated code base read by an LLM to yield answers to questions.
Already now, the most popular open source projects seem to prioritise guides for common use cases over extensive documentation.
- jaggederest 3y agoI'm pretty sure both of those count as documentation. https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o... I think you mean something a bit more specific, maybe "comprehensive reference documentation written by humans", though I'm not sure codebase annotations get away from that.
- madsbuch 3y agoYep, you are right. I was not precise enough.
- jitl 3y agoI disagree. Golang and its standard library are terrifically productive for me because they have plain old high quality module documentation on every public struct and function. Of course you need a few tutorials to introduce people to a library’s main use cases but after building that initial familiarity I find the kind of docs Go has to be the most useful for me. A doc browser like Dash (Mac) or Zeal (open source) that makes search lightning fast multiplies the helpfulness of that kind of docs.
- madsbuch 3y agoWow, that was indeed a hot take in my original comment. Net 5 downvotes for a comment that is not at all slurs and represent a genuine opinion about the future of software development. Anyhow, I am concerned about how the new wave of AI tech is going to affect the software development market. A lot of people are focusing on code synthesis. I don't think that is just around the corner. I think think it is going to be in assistive technology, such as learning / helping writing code. I also think a lot of contemporary programmers are attached to documentation and overly focus on it's value, which indeed was important in an age of that being the only way to disseminate the intended workings of a library. I can say that already know https://inkeep.com/ https://inkeep.com/ is working on this type of tech (The I prefer over reading documentation on bun.sh), Pulumi also have https://www.pulumi.com/ai https://www.pulumi.com/ai that I prefer over reading Pulumi's documentation. Anyhow, the future will show how this works out.
- otterley 3y agoI won’t merge any PRs to my open source projects without a corresponding documentation change. I think it’s a good rule that everyone should follow as it benefits both the user and the project’s other developers.
- pyth0 3y agoIs the documentation for your projects all contained within the same repo as the code (and if so what are you using to render/view it) or do you just require an accompanying PR to wherever your docs live?
- otterley 3y agoSame repo.
- madsbuch 3y agoI think that is a dogma future software developers seriously need to reconsider. Naturally, you are free to impose whichever dogmas you believe in for your own code bases.
- otterley 3y agoWhy do you believe it to be a bad rule?
- madsbuch 3y agoI don't know if it is a bad rule. I am just questioning the return of investment on human written documentation. From my perspective, it seems to have diminishing value as we are getting other means of disseminating software documentation.
- otterley 3y agoAre you seriously questioning whether there are significant productivity improvements and customer satisfaction gains associated with having timely and accurate documentation? Also, how do you disseminate documentation that does not a priori exist? It doesn't come out of thin air.
- Karellen 3y ago> nobody wants to read [documentation]. OP wants to read documentation. It's in the article. Quite a few commenters say that they're resorting to LLMs, not because that's how they want to learn about the code they're using, but because the documentation is terrible and LLMs summarising snippets from dozens of different forum questions and blog posts is the only alternative they have to terrible documentation. > most popular open source projects seem to prioritise guides for common use cases over extensive documentation. Open source projects that people aren't being paid to work on probably don't have extensive documentation, because writing extensive documentation is hard, and the kinds of people who like hacking on code that solves their problems are probably not people who enjoy writing extensive documentation when they could be implementing another feature. Even if a large segment of their users would prefer that, and it's what would be best for the project.
- madsbuch 3y agoYou beautifully highlight the economics behind why this is the future of documentation: > the documentation is terrible and LLMs summarising snippets from dozens of different forum questions and blog posts is the only alternative they have to terrible documentation. and > aren't being paid to work on probably don't have extensive documentation This will only get strengthened when people discover that the outputs of LLMs suffice.
- pasc1878 3y agoAnd that is why it is difficult to learn new things. I want to read documentation but then I have been programming for 45 years and am used to reasonable documentation. If you are not experienced in language X the being told to look at its source code to see what and how it works is not good as the reason you are asking is because you don't yet understand X. Documentation has to be written assuming you don't know what is happening. Even UNIX/Emacs documentation is frustrating as if you know Unix/Emacs than searching will give the information you need but if you have not user that port before then the documentation is opaque. I suspect that documentation works when it is written by a separate team than the developers of the product and the documenters use the product.
- madsbuch 3y agoMy expectation is that a LLM can assist with exactly this. It would even be able to be lead by what you tell it that you know – and it can do it much more cheaply than humans.
- pasc1878 3y agoUnfortunately current LLMs also produce false code. Possibly because they do not have enough correct documentation to build models from.