this post was submitted on 20 Dec 2023
158 points (88.0% liked)
Asklemmy
43905 readers
1039 users here now
A loosely moderated place to ask open-ended questions
If your post meets the following criteria, it's welcome here!
- Open-ended question
- Not offensive: at this point, we do not have the bandwidth to moderate overtly political discussions. Assume best intent and be excellent to each other.
- Not regarding using or support for Lemmy: context, see the list of support communities and tools for finding communities below
- Not ad nauseam inducing: please make sure it is a question that would be new to most members
- An actual topic of discussion
Looking for support?
Looking for a community?
- Lemmyverse: community search
- sub.rehab: maps old subreddits to fediverse options, marks official as such
- !lemmy411@lemmy.ca: a community for finding communities
~Icon~ ~by~ ~@Double_A@discuss.tchncs.de~
founded 5 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Fair enough but writing a readme isn‘t, right?
That's the most painful part of all.
Asking for a friend: do you code? Because most coders say this and thats my initial point. :)
I'm not a coder but I relate to being a lot more attracted to the idea of problem solving than writing a well-formed document that communicates ideas clearly, haha.
Well, then I can relate because I have this exact situation on lemmy (and IRL) but I write good handbooks and readmes.
I‘m more of an entry level coder and I havent studied IT so I have no idea what the dev thought making something but I know what would have helped me to use it.
What use is a readme written by someone who doesn't know the code, doesn't know the internal designs, the design goals, the plans of the current maintainers, anything? It'd be no better than asking ChatGPT to write it for you.
I‘m sure a lot of people who correct text, add references, structure and pictures to a readme would disagree with you.
I‘m not sure if you‘re a coder but it you are, you should know that coding and usability are two entirely separate things.
Oh...
You don't mean the readme file. You are talking about the manual, or the explanations on the website. Yeah that can make sense. Though I would still say it's weird if you're not too familiar with the direction the application is going, but an experienced user can of course help create better texts and pages for that.
Easy, just click the whatchamacallit, and add that little do-hicky!
This is why all my methods are called ˋdoStuffˋ.
Exactly. Thanks :)
Yeah, that's a good point, but the readmes that I've seen written by those who wrote the code themselves are not much better. Sure, they know what it's all about, which is precisely why it oftentimes isn't much help for a user.
What's needed is someone who'd read the initial readme (written by the guy who wrote the code itself) and ask questions about the parts that were "too straightforward" to be included, or weren't explained clearly enough, or to bring down the general overview back to Earth.
And if there's yet another person who'd go over this second pass, and keep it from being too dumbed down, even better. Keep it to the level of the average user. That requires knowing the kind of person who'd likely use the program.
Why does it have to be documenting internal designs, architecture, and all that? Why not app user manuals or install guides or any of myriad other sorts of documentation?
Just because one specific scenario may not be suited doesn't mean no scenario is suited to what op is proposing.
I mean first, what kind of projects are we even talking about, libraries? APIs? Apps? Command line tools? Etc?
Because the technical writing needs vary depending on what kind of project. They don't all require coding skills for success.
Technical Writer is a skill. It's a fairly well paid one too.
Being able to make good documentation is hard.
User Experience (UX), user interface (UI), and graphic design are all also surprisingly difficult. Much of which is integrally tied to the code.
I came here to say something similar.
Just writing documentation alone, is a skill worthy of a full-time job! Of course, there'd be people who can volunteer their time to do that, but without someone with such skill at least taking a look and making sure it's understandable to someone who's got no idea what's going on? Let's just say that open source software help documentation is filled with such examples.
Yeah, I probably should think about taking money for it but making descriptions and manuals is just something I like to do. And there are a lot of people who also do this but dont call it „technical writing“. Often it is things like doing glossars or explaining abbreviations. That helps a lot.