There are so many tools to make documentation for your project. LATEX is a great one, and you can use it to easily host your documentation online. And it’s really not difficult at all to do by hand. If you can have it on discord you can certainly have it in a repo.
Maybe it’s a cynical ploy to increase community engagement with their project by getting them into the discord. Regardless, it gives me The Ick. Very gross.
LaTeX is great, but I prefer Markdown for software documentation (bonus points if your flavor of markdown supports LaTeX-style math). Standard LaTeX is geared towards typesetting and formatting, which is great for reports and journals, but not so much for software documentation, so you end up with a lot of boilerplate. Markdown syntax is also more accessible to beginners, I feel. And if you have a really big project that requires features like cross-references, there’s things like myst markdown.
Both are powerful tools, though with different strengths as you describe. I was thinking more with automation in mind. But regardless, anything is better than a discord server. Even .txt documentation!
I personally don’t like LaTeX for documentation because it doesn’t benefit much from advanced features of LaTeX, while being more difficult to read/write than Markdown.
Discord is great for building a community because it’s the defacto chat service for communities. It replaced IRC and does that quite well. Having a place to casually chat with people more invested in the project has its advantages.
Now I really dislike it if they think discord can replace a wiki. Iirc discord added a wiki-like feature a while ago and it’s terrible because it’s not indexable by search engines.
I think you give Discord too much credit even with that. They’re closed source and have very little openness with their data. We have no clue how they store and archive our data and conversations, or what they do with it. I don’t think the open source community should trust Discord an inch.
I’m really hoping an open source alternative starts gaining traction.
A agree with everything you just wrote. Discord is the platform of choice for many projects because most people are already there, so it increases engagement (and often enough some people actually ask for an official discord).
I personally prefer projects to use matrix, despite all it’s faults. Some already do.
It’s not really about the tools, we have plenty of tools, plain text, markdown, latex, web pages. Putting content to readable format is the easy part.
The hard part is knowing what to put down and how to organize it, and making sure that your documented explanations are actually understandable.
Particularly when you want to get traction going you might really want conversations to help you understand where the project needs fixing versus how documentation needs fixing and get a sense for what documentation might be helpful.
There are so many tools to make documentation for your project. LATEX is a great one, and you can use it to easily host your documentation online. And it’s really not difficult at all to do by hand. If you can have it on discord you can certainly have it in a repo.
Maybe it’s a cynical ploy to increase community engagement with their project by getting them into the discord. Regardless, it gives me The Ick. Very gross.
LaTeX is great, but I prefer Markdown for software documentation (bonus points if your flavor of markdown supports LaTeX-style math). Standard LaTeX is geared towards typesetting and formatting, which is great for reports and journals, but not so much for software documentation, so you end up with a lot of boilerplate. Markdown syntax is also more accessible to beginners, I feel. And if you have a really big project that requires features like cross-references, there’s things like myst markdown.
Both are powerful tools, though with different strengths as you describe. I was thinking more with automation in mind. But regardless, anything is better than a discord server. Even .txt documentation!
I personally don’t like LaTeX for documentation because it doesn’t benefit much from advanced features of LaTeX, while being more difficult to read/write than Markdown.
Discord is great for building a community because it’s the defacto chat service for communities. It replaced IRC and does that quite well. Having a place to casually chat with people more invested in the project has its advantages.
Now I really dislike it if they think discord can replace a wiki. Iirc discord added a wiki-like feature a while ago and it’s terrible because it’s not indexable by search engines.
I think you give Discord too much credit even with that. They’re closed source and have very little openness with their data. We have no clue how they store and archive our data and conversations, or what they do with it. I don’t think the open source community should trust Discord an inch.
I’m really hoping an open source alternative starts gaining traction.
A agree with everything you just wrote. Discord is the platform of choice for many projects because most people are already there, so it increases engagement (and often enough some people actually ask for an official discord).
I personally prefer projects to use matrix, despite all it’s faults. Some already do.
I’ve not heard of matrix before. Looking it up, it looks pretty cool. Kind of a terrible name tbh.
It’s not really about the tools, we have plenty of tools, plain text, markdown, latex, web pages. Putting content to readable format is the easy part.
The hard part is knowing what to put down and how to organize it, and making sure that your documented explanations are actually understandable.
Particularly when you want to get traction going you might really want conversations to help you understand where the project needs fixing versus how documentation needs fixing and get a sense for what documentation might be helpful.
LaTeX produces PDFs, which are hard to read on small devices. Just write a website.
LaTeX can produce .html with links. It can litterally generate an entire documentation website.