Conversation

Notices

1. Embed this notice
   Adrianna Tan (skinnylatte@hachyderm.io)'s status on Wednesday, 24-Sep-2025 15:03:58 JST Adrianna Tan

   This satirical blog post really illustrates the problem with a lot of technical writing. Amazing technical writing is so good and then everything else reads like this

   https://anniemueller.com/posts/how-i-a-non-developer-read-the-tutorial-you-a-developer-wrote-for-me-a-beginner

   • Embed this notice
     Raven667 (raven667@hachyderm.io)'s status on Wednesday, 24-Sep-2025 22:35:02 JST Raven667

     in reply to

     @skinnylatte Honestly this joke example is better than some of the technical documentation I've read, as a software developer / sysadmin, at least it lists the path you are expected to find some config file in, so many docs will just say "and go change the foobix setting in the config file" without ever saying _where_ the config file is located (or what you are supposed to change it to), so you have to strace the process to figure out where it loads configs from which is a ridiculous thing to have to do. Or something will say to "frobnicate this setting" but won't tell you what the setting actually _is_, is it "setting=Frobnicate" capitalized is it "setting='frobnicate'" in quotes is it "setting=3" (where 3 is defined as Frobnicate somewhere else), or is it "setting: { value='Frobnicate'; }" or some other format. Even better when there isn't a message about an invalid setting, so guessing wrong just doesn't work with no indication as to why. A simple example could clear up so much confusion from trying to describe things in words, badly, but is sometimes mission impossible.

   • Embed this notice
     Adrianna Tan (skinnylatte@hachyderm.io)'s status on Thursday, 25-Sep-2025 01:35:29 JST Adrianna Tan

     in reply to

     • hypolite
     • A Sweet Gentleman

     @hypolite @aSweetGentleman @annie yay! It was so good

   • Embed this notice
     hypolite (hypolite@friendica.mrpetovan.com)'s status on Thursday, 25-Sep-2025 01:35:31 JST hypolite

     in reply to

     • A Sweet Gentleman
     @skinnylatte @aSweetGentleman Annie is even on Mastodon! @annie
   • Embed this notice
     Adrianna Tan (skinnylatte@hachyderm.io)'s status on Friday, 26-Sep-2025 04:04:32 JST Adrianna Tan

     in reply to

     • Howard Chu @ Symas

     @hyc good technical writing understands the audience and purpose. Not everybody has to understand all the things, but many FOSS tutorials for beginners are very inaccessible, and I hope that improves. Documentation that clearly describes who the docs are for and are not, are useful too.

   • Embed this notice
     Howard Chu @ Symas (hyc@mastodon.social)'s status on Friday, 26-Sep-2025 04:04:33 JST Howard Chu @ Symas

     in reply to

     @skinnylatte 1st, while it may kinda suck, you should be grateful anyone bothered to write anything down at all. Searching on a question and finding no answers would be worse. At least with even an incomprehensible answer, you have a chance to search further for details on the specific parts you don't understand. All this of course assumes the writeup is correct, of which there's no guarantees.

   • Embed this notice
     Howard Chu @ Symas (hyc@mastodon.social)'s status on Friday, 26-Sep-2025 04:04:33 JST Howard Chu @ Symas

     in reply to

     @skinnylatte 2nd, we write to the audiences we're familiar with, and every field has its own jargon. It would cost too much time to spell out every term of the art for any non-practitioner's benefit. We don't want to build the universe just to describe how we solved the latest puzzle we were working on. If you're interested in the puzzle, you have to meet us where we live. If you won't do that then you probably won't understand the solution anyway.