this post was submitted on 28 Jan 2024
2039 points (98.2% liked)
linuxmemes
21381 readers
3292 users here now
Hint: :q!
Sister communities:
Community rules (click to expand)
1. Follow the site-wide rules
- Instance-wide TOS: https://legal.lemmy.world/tos/
- Lemmy code of conduct: https://join-lemmy.org/docs/code_of_conduct.html
2. Be civil
- Understand the difference between a joke and an insult.
- Do not harrass or attack members of the community for any reason.
- Leave remarks of "peasantry" to the PCMR community. If you dislike an OS/service/application, attack the thing you dislike, not the individuals who use it. Some people may not have a choice.
- Bigotry will not be tolerated.
- These rules are somewhat loosened when the subject is a public figure. Still, do not attack their person or incite harrassment.
3. Post Linux-related content
- Including Unix and BSD.
- Non-Linux content is acceptable as long as it makes a reference to Linux. For example, the poorly made mockery of
sudoin Windows. - No porn. Even if you watch it on a Linux machine.
4. No recent reposts
- Everybody uses Arch btw, can't quit Vim, and wants to interject for a moment. You can stop now.
Please report posts and comments that break these rules!
Important: never execute code or follow advice that you don't understand or can't verify, especially here. The word of the day is credibility. This is a meme community -- even the most helpful comments might just be shitposts that can damage your system. Be aware, be smart, don't fork-bomb your computer.
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
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.
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.
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.