tudsworth

- ̗̀ 🏳️‍⚧️Tuddy🏳️‍⚧️ ̖́-

@tudsworth

- ̗̀ new ̖́- trash mammal

  • they/them

33, kuso anime boy who likes video games, definitely not a skunk in real life.

Switch friend Code : [SW-1872-7002-1339]
XBox Live : Tudsworth

log inask
tudsworth
@tudsworth
Loosf
@Loosf
doomishfox
@doomishfox

what the heck happened to documentation

that explained how something worked instead of just being a collection of quickstart guides? no i dont want to lean how to Set up a quick app in under 5 minutes! i want to understand what the fuck your code does

NireBryce
@NireBryce

I think some of this comes down to the fact that in the zeitgeist, documentation submissions aren't talked about much and most people don't know they can just submit some, and so there's a drought of technical writing that should be being done but instead goes on stack overflow and personal blogs, because:

  1. most people just don't know about it being a thing
  2. a lot of projects are prickly enough about it that it's just not worth it
ireneista
@ireneista

on technical writing and tech culture

yeah. technical writing is an incredibly important skillset which engineers need to understand that they do not have. it is a role that needs to be filled by someone who has gone very deep in the writing skill tree. organizing ideas is a writing skill. figuring out what documents should exist but don't is a writing skill. fixing the names for things that are confusing is a writing skill, although that's one where engineers are justified in being a little bit territorial, sometimes, maybe.

so many free software projects are organized as essentially a personality cult around one person's ego; we would go so far as to say that sometimes that's the reason the software exists in the first place. (we refuse to give examples for this, because that would start fights. as a homework exercise, think of three examples for yourself now, or if you don't have any, the next few projects you run into, stop and ask yourself if you see that pattern.)

working as part of a team means recognizing that there is more than one skillset necessary to do a good job, it means valuing those contributions, it means making sure that when people with a writing background chip in to help, they feel welcome and they know that their work is appreciated.

documentation is the public face of any software project! it is the first thing that newcomers see! if one of your goals for a project is that it will attract a broad base of users at a variety of experience levels, documentation should be among your top priorities!

SixArmedSweater
@SixArmedSweater

This is actually what half of my degree is in! (The other half is psychology.) It is absurd how bad most folks and most COMPANIES are at this! Unclear documents written for and by people who already understand the material, deprecated and neglected procedure manuals, the whole works! It’s a vital field that’s absurdly neglected.

You must log in to comment.

in reply to @ireneista's post:

arborelia
@arborelia

it seems to me like many developers do understand that writing documentation is a skill they don't have. That's why they write "Set up a quick app in under 5 minutes!" and assume they can find someone to write the docs later

login to reply
leftpaddotpy
@leftpaddotpy

i think this goes similar ways to people in closed source codebases writing things that really ought to be part of some library, or me patching nixpkgs in overlays, or anything like that.

it's so much easier to do the thing that doesn't involve open source contribution processes that can require up to an arbitrary amount of work, even if it's antisocial.

so yes i write blog posts about stuff instead of contributing to official documentation: there's somewhat more personal benefit but more relevantly, there's fewer actions requiring executive function involved and so it gets done.

i think that there's a lot of value in people more able to deal with the process to go and port/synthesize writing to more easy to find spots.

login to reply
prox
@prox

interesting. as a writer who loves reading and learning about tech and tech concepts but doesn't Do any actual tech maybe this is a field i should look into, i would really enjoy that. somehow i never really knew what "technical writer" was and thought it was too deep in the Engineering skill tree for me.

login to reply
ireneista
@ireneista

the technical writers we know do have engineering skills for sure, communicating with engineers requires that, but it is a writing skill first and foremost. if you are able to sort through the concepts and make sense of them, and can read code, it can't hurt to look into it.

login to reply
fizbin
@fizbin

That ability to read code isn't even needed if you have regular access to an engineer who can answer your questions about how things work.

I find that the skills most engineers fall down on w.r.t. technical writing mostly fall into two categories:

  1. Failing to organize thoughts within a given document in a coherent structure for the reader. E.g., simple things like not using a term for several paragraphs and only then telling the reader what this term means, but also more fundamental things like never considering the question "What should this document tell the reader?".
  2. basic failing at human language at all. It turns out that spoken, interactive English and written English are different languages; you often see this when people transcribe someone speaking spontaneously on the news to make the speaker seem an idiot. Interactive English is full of half-spoken words, repetitions of sentence fragments as you check with your conversation partner for understanding, loads of "um", "uh", flailing for the right word, unclear divisions between one sentence and the next, etc. Now imagine someone taking a recording of normal human conversation between people not trained in giving media interviews and running it through text-to-speech. I have read this documentation. Native English speakers often fail in this manner more frequently than non-native speakers because non-native speakers know that they are writing in a foreign language and will usually construct their sentences, and when making errors will do so in some pattern that makes sense given their origin language. Native English speakers show no such restraint.

I find that the second failing is something engineers often write their own way out of with age, but without deliberate training the first failure mode remains.

login to reply
fizbin
@fizbin

I have been told by those who read what I've written that (relative to other engineers) I have some amount of skill in writing documentation.

What I do not have, however, is what I'll call "documentation spoons". Writing documentation is a task I find incredibly draining and exhausting. I can get deep into a code change and be "in the zone" modifying half a dozen files for hours to the point that I skip meals and need to be reminded to eat and that doesn't compare at all to how I feel after a day of writing documentation. After a day of writing documentation my brain is just shot and I can't even watch TV if I'd need to pay attention to dialogue.

It's conceivable that this is something analogous to working out and training an underused muscle, and something that would get less laborious with practice, but I have no plans to find out.

login to reply

in reply to @SixArmedSweater's post:

Pinned Tags