full image - Repost: Increasingly frustrated with tutorials, and even official documentation. (from Reddit.com, Increasingly frustrated with tutorials, and even official documentation.)
Mining:
Exchanges:
Donations:
This is mostly a general rant about software, but it also applies to homelab techniques and software setup as an end user. If you are a developer, PLEASE learn some lessons from this.I'm not a complete noob with networking, homelab or computer science. But I am a self-taught amateur who's trying to set things up the correct way and learn how to do things to an industry standard. I like to read official documentation and learn how the creator intended the system. That said, I definitely don't know it all and I definitely experience trial and error setting things up. Eventually I prevail, or I move onto a system that actually works without much fluff.I am getting incredibly frustrated with poorly or half-baked information.How is it admissible to have documentation only understandable from the creator's perspective, if even that? From experience, the software I use at work (unrelated industry, but technical and closed-source software reliant) is horrendous. The official manual that comes with the software will quite literally reference a function ("explode" as an example) and the entire entry for the "explode" function will say: "explodes selection."Yeah, I friggin know that, as that's what's on the hover tooltip.You can extrapolate this across the entirety of the software, with nearly every function. What is not in italian (yes, even in the english translation of the manual, there are whole pages still in italian) is in broken english, and most of the english manual is like this, very terse self-references to the function or situation at hand. This software costs 5k+USD, and if you don't know something, you have to ask a representative from the company, who is very short with you because they're constantly on the phone with customers either fixing a software issue, or explaining things they could just put in the manual.This is happening in homelab situations as well. "What goes in the IP ADDRESS field?" "The host IP address" "It's a router. The internal or external side?" "WAN" "Okay, what does the tunnel connect to on the other end?" "LAN"great, thanks.Made up scenario, but this is what I've been dealing with trying to get an understanding of some things, and every thread you go into for someone else asking a question has post after post of the poor OP saying "but.. but... but... but..." The lesson is, if you don't want anyone to ask questions and just "get it" in one post, give all the information. explain the thing, don't just list off terse facts you know and expect everyone to understand it like you do with no further explanation. If you're writing a manual, made it detailed and cover all the bases. I'm really tired of seeing "IP FIELD: IP of the host" when there is definitely more to it than that in some situations.PLEASE, if you're writing a manual, documentation, tutorial, or a help post, PLEASE keep the details and don't just expect that people understand from your 20 years of experience and a three word post. The less questions people need to ask setting up, the better."read more." Read more what, other people saying the same one liners as you?I know I'll get flak for this, don't care. I know I'm right about this one.edit: removed some fluff.
Social Media Icons