this post was submitted on 02 Aug 2024
789 points (96.7% liked)
Selfhosted
40347 readers
328 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
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
Yes. Here: "1.You aren't writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
"2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOP"
"3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess."
"4. Everyone is fucking stupid, be clear, and verbose." We're talking about where the start menu is, clicking on the "OK" for prompts, how to spell and type things out.
Change my given values per SOP and what it's for. But those are my main tenants.
Excellent notes. If I could add anything it would be on number 4 -- just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like it's astro glide and you're trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
I agree, but I don't think images should be relied on as the primary communicator. I have seen far too many forums/websites/docs with broken images because the host went down. That and archivers are more likely to fail at saving images. Explain it using text and give a reference image to further display the point.