But the ones who need to "gorge on it" can't, because there is no good way to extract, catalogue, organize, archive, or search it.
Yes documentation isn't sexy. It's boring, it's tedious, and I can understand everyone who doesn't want to do it. And it's also key to a projects long term viability. If the only documentation for a project is "the discord", I won't use it, even if an alternative is a less optima technical fit.
Because if I have to come back to fix an issue 2 years later, and I need the documentation, I'd rather read a badly maintained, badly formatted 90s style HTML-ony page, than stare in frustration at an info telling me the discord channel no longer exists.
People read the documentation and fails to understand it. Writing good clear documentation that successfully guides your users or customers to gain the most value from your product is incredibly hard.
It's fine to have Discord, or something similar, for when you users come to you with a problem, but then you need to consider if you have to go back at update the documentation. Early in my career hanging out on mailinglists was much more popular, frequently you'd ask a question and the maintainers of whatever software you where using would take the answer and put them into the regular FAQ or documentation. Now we replaced Discord with mailinglists and that might be sensible, the feedback loop just should not be excluded. Discord is terrible place to store knowledge.
Maybe that is not the issue. Maybe it is merely a symptom of how ephemeral and temporary existing systems are and 'Discord4Documents' is just a lazy way to port all the unsexy documentation to one place so that the ones that need to gorge on it, can.
Right, but that's "support", not "documentation". Completely different thing, and the latter is not really a substitute for the former, whether it's on Discord, IRC, XMPP, or at the bar after a conference.
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
Documentation was a bad idea. The only problem Documentation might solve is that Stack Exchange Inc has a bunch of developers and they have to keep them busy doing something. All the thrashing and weird incentives and bullshit flows from this truth: the users and community don't need anything like this Documentation.
People didn't put documentation in IRC channels because they didn't want to answer the same questions over and over. Info went into a wiki, and you would get flamed for asking a question on IRC that was answered on the wiki. Discord is not a good place to stash documentation.
The documentation does _not_ suck. It it literally the most well documented software in existence, a reason for which it has been used for many different things outside its original purpose of text editing.
Yes, it may not be for everyone. But just say that, that it uses certain conventions that are likely outdated for a reasonable set of the population. But you can't say the documentation sucks when you have the below:
We use it for new things - I think the last thing I wrote with it was a custom dynamic dns server we needed - that was just a few weeks ago I think.
Yeah, the documentation is awful. Fortunately I've pretty much always just assumed that all documentation is going to be bad, so I pretty much never even bother trying - I just read the source.
You 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.
reply