this post was submitted on 02 Aug 2024
33 points (94.6% liked)
Selfhosted
40152 readers
474 users here now
A place to share alternatives to popular online services that can be self-hosted without giving up privacy or locking you into a service you don't control.
Rules:
-
Be civil: we're here to support and learn from one another. Insults won't be tolerated. Flame wars are frowned upon.
-
No spam posting.
-
Posts have to be centered around self-hosting. There are other communities for discussing hardware or home computing. If it's not obvious why your post topic revolves around selfhosting, please include details to make it clear.
-
Don't duplicate the full text of your blog or github here. Just post the link for folks to click.
-
Submission headline should match the article title (donβt cherry-pick information from the title to fit your agenda).
-
No trolling.
Resources:
- selfh.st Newsletter and index of selfhosted software and apps
- awesome-selfhosted software
- awesome-sysadmin resources
- Self-Hosted Podcast from Jupiter Broadcasting
Any issues on the community? Report it using the report flag.
Questions? DM the mods!
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
Yeah the documentation (if it even exists) of most projects is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it. But writing good detailed documentation is also really hard, especially for a specialist because many nontrivial things are trivial to them and they believe what they're writing is thorough and well explained even though it actually isn't.
Relevant xkcd
Bold of you to assume I know how to read!
This is why Technical Writer is a full time job.
It's also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
My CS major required me to take two upper division English classes and I think they helped me more in my career than my upper division CS classes. People forget that documentation is for ourselves too
Maybe, just maybe, people have different strengths and weaknesses and cooperating around our differences is what makes us succeed.
If you know your weakness is writing documentation, please hire a technical writer.
That's exactly what I'm saying, sorry if it came across somehow askew.
My point was there is no point in competing over whose job is "better", we should be working together.
"set all environment variables"
More recently its go to discord for the env....no joke.
My face actually dropped when I read this. I will be so mad if I ever encounter this live.
It sucks....and seems to be catching on. Ive seen a quite a few on GitHub that are now referencing using it instead of the issue tracker.
That is so depressing. Literally a markdown file in the repo would be a better issue tracker.
Donβt forget to run your shell over Discord!
This is cursed, but also cool. Hijack another platform for your authentication
This is why I did a βwalkthrough testβ when I had to write documentation on this sort of thing. Iβm a terrible technical writer, so this shit is necessary for me.
I grabbed my friend who knows enough about computers to attempt this, but not enough about infrastructure to automatically know what I meant when I was too vague.
Took two revisions, but the final document was way easier to follow at the end
That's why blog posts rock. Most popular projects will have a dozen blog posts for different configurations. For example, when looking to set up NextCloud, I found docs for almost all combinations of the following:
It does take some knowledge of each of the above if you need one of the few configs that's not available on a blog post, and some of the posts are outdated, but with a bit of searching almost everything is documented by someone on the internet.
This shouldn't be necessary (official docs should be more comprehensive), but at least it's available.
Okay, please point me to the blog posts that helped you with collabora/onlyoffice. Thanks have NEVER been able to get that to work with my nextcloud (currently using the Docker AIO).
The mistake is the assumption of a certain level of end user knowledge.
You have to assume some level of end user knowledge, otherwise every piece of documentation would start with "What a computer does" and "How to turn your computer on."
I've found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.