#tech writing

[fujocoded]

Geese, Guides, and Good Luck Cookies 🪿📔🥠... and a (paid) Call for Writers 📝💰

It's out! Check out this month's update, including: our visit to #ATmosphereConf (feat. geese yaoi 🪿), our plans for the fortune cookies revenue 🥠, news on the GitHub Guide Beta and... A 💰PAID💰 opportunity for daring—not to mention aspiring—tech writers 📝⬇️

Call for hire

This month we’re once again happy to share a paid position: come forth technical writers (and aspiring such), and let us bring you on a Now Paying Money adventure!

Smithing Words📝…for Money (💰): After much time, feedback, and outlining, the “Introduction to JavaScript with NPM” articles financed through our founding campaign are ready to be written! Now we’re finally looking for technical writers (fannish background appreciated) to help us inspire new, confident explorers of everything the NPM ecosystem has to offer—and yes, we (also) mean Astro. Check out some of the articles in our learning website for an example of what the final artifacts should look like, and get in touch if you’re up for the (paid) task! We require both basic computer knowledge and the willingness to run simple command line programs, but we don’t require previous experience with professional technical writing NOR pre-existing knowledge of NPM/JavaScript. Just send us some tutorials or other explainers you’ve written!

Smithing Videos📹…for Glory: Are you willing to wrangle video wranglers? BobaBoard’s documentation bubble is looking for a wondrous lead volunteer to coordinate our wonderful video volunteers as they turn our many, many hours of recorded web development and BobaBoard documentation into something the whole FujoVerse™ and beyond can put to good use. If you have previous experience with managing work on video, or have been part of similar work and want to build some managing experience of your own, reach out!

If any of these calls for aid sound up your alley, or if you’d like to get involved in other ways, please reach out at contacts@fujocoded.com or via DMs!

[sweaterkittensahoy]

As someone who works under an NDA basically all of the time (I wrote maintenance for a non-USA Airforce One at one job*), the continued War Thunder leaks are so fucking funny.

Not because it's not serious. It is. But it's also SO DUMB. These people can't fucking stop themselves from proving they know about the coolest war machine even if it means literally committing some light treason.

Like. No amount of Infosec training in the world can stop them. Forum members--even those who HAVEN'T shared classified or top secret documents--can't get jobs where they have access to classified or top secret documents.

That's how hilariously terrible these people are at not needing to be the most right on the internet.

(*that was a cool fucking plane with the same out-of-box toilet as every other plane I wrote about at that job)

[fieldbears]

Hi! Thank you for doing this AMA! How did you get started in on your career path? I feel like I keep hearing either "know somebody who has faith in your ability to write technical documents" or "write technical documents for fun" both of which I'm not certain how to start.

Great question! In grade school, my friends and I were little nerds who wrote and traded stories with one another. We were giving honest feedback, learning, writing more, rinse and repeat. A couple of summers, we took writing workshop classes. We learned the general style of workshop critiquing. Being able to deliver and receive criticism is a valuable life and career skill.

Fast forward, I went to college, majored in English with an informal focus on modern literature, and took more creative writing classes! Having been in a workshop environment as a kid REALLY helped prepare me for the ones in college. Not everyone in those classes knew how to receive even very gentle criticism. Learning how to re-calibrate for them was its own learning experience. Another skill!

Fast forward again and I'm in the job market. I thankfully had a friend whose company was hiring, and that started my personal ball rolling. I got in through a friend, yes, but my career advances have been because I'm incredible. :)

But don't get it twisted. Most of the stuff in my background was completely unnecessary to getting an entry-level position. They helped me keep the job, and get more jobs, and get promotions, but nobody is expecting all that workshop experience. If you have average or higher people skills, you can teach yourself how to gently deliver the news that someone is functionally illiterate and you need to fix their work.

What you should have: a 4-year degree majoring in English, a relevant STEM field, or Communications, in that order. You should be ready to clean up a "test" document as part of your interview. You should probably pay close attention to the job description you're applying for, because 'technical documentation' is a really broad field and you need to be able to prove you're ready for whatever flavor they're asking for. Are you writing instructions (how to operate a device)? Processes (how to onboard an employee)? How much of your job will be interviews with SMEs (Subject Matter Experts)? Are you writing a new document at all or updating something that's outdated or untested? You can do some light testing of software, right?

If the interviewers are smart, they will ask you your plan when you're asked to make a new document. Have an answer ready. The information I always want first is: who is this for? Let's say it's an internal guide for some software your company uses. Is everyone on the project an engineer who's very familiar with computers? Or, is it a more generic office, where a 64-year old named Eustace will need very clear instructions on where the start button is? That information is a starting point for figuring out what your document should be.

So tl;dr: 1) Have a relevant degree. 2) Know the specifics of the position. 3) Be ready to walk interviewers through the steps you'd start taking to make a requested document.

Hope this helps <3

[dnschmidt]

What It's Like Being A Tech Writer

Engineer: I need documentation for this project. It’s super urgent!

Me: Sure. Can you send me the details?

Days pass.

Weeks.

Months.

Centuries.

Empires rise and fall.

Cockroaches evolve intelligence.

Octopuses develop their own space program.

The old gods return.

The stars die out and the sky goes black.

Engineer: Here you go.

[dead-documentarians-society]

A Tech Writing Community of One’s Own

Documentarians, have a community.

Share ideas

Ask questions

Get extra eyes

Share tools

Rib product managers

Comisserate

Ideate

Incubate

Peer review

Share solutions

Grow a network

We are each others’ most reliable rubber duckies.

Invite others with https://www.tumblr.com/join/bYNj2jMH.

[gentlewomanquietlight]

prayers for my job search would be appreciated

i'm looking for a tech writing job with remote/hybrid capabilities

[technoor]

How to Improve Technology Blog Writing

Writing a tech blog seems easy at first. But clear, engaging content takes skillful, careful work. Let’s explore smart ways to level up writing.

Before You Start Writing

Always think about who reads your tech blog. Do they want simple guides or deep technical stuff? Knowing this shapes tone, style, and detail level. Use language your readers easily understand each time.

Write in Simple Words to Explain Tech Ideas

Avoid jargon that confuses regular tech blog visitors. Break complicated topics into small, clear explanations always. Use examples or analogies that everyone relates to. This makes your blog friendly, warm, and helpful.

Organize Content with Headings & Short Paragraphs

Big walls of text scare many readers away quickly. Split ideas into short paragraphs of three lines. Use headings & subheadings to guide people smoothly. This keeps their eyes moving through your article.

Use Bullet Points & Numbered Lists Often

Lists break information into clear with snack-size bits. They help people scan quickly for key insights. When explaining steps, always use easy numbered points. This builds trust because readers follow instructions easily.

Add Real Examples and Personal Experiences

Readers love stories from real tech situations always. Talk about how a plugin failed your website. Share fixing a laptop with quirky software problems. Personal stories keep blogs human, not boring manuals.

Include Screenshots or Images to Show Points

Visuals often explain more than words alone can. Add screenshots, charts, or funny GIFs when helpful. It breaks up text and keeps interest very high. Also helps technical people follow along step by step.

Edit, Proofread, and Read Posts Aloud

Never publish tech posts without reading them aloud. You catch awkward phrases and spelling errors easily. Proofreading makes sure everything flows smooth and natural. It shows you care about quality for your audience.

Final Tip: Write Often to Get Much Better

Practice writing daily on new tech blog topics. Over time, you find your voice becomes clear. Writing often builds confidence and improves your explanations. Keep going, and your readers will love returning.

[savagegardensprogramming]

Smart Documentation

I’ve made the decision to tightly integrate documentation into SavageGardens. I hesitated to talk about this aspect of SavageGardens because programmers don’t think of documentation as a language. Still, the goal for SavageGardens is to extend our ability to manage massively complex projects. Documentation is important for large projects, therefore I am including it.

It is a somewhat controversial decision to include documentation as part of the source code. It makes SavageGardens a rather complex application in itself. I am actually asking to integrate a wiki data and discussion forum data inside the source code. It changes the face of SavageGardens but, so be it. I see it as the future. A future which I first saw in StarTrek the Next Generation. That TV Show has several scenes where Geordi La Forge documents his work and accesses documentation. That is the goal. That is the dream.

In SavageGardens, Sub-Layer 0 or the ground level is designated for this purpose. Everything on this layer is strictly for human consumption. Human-to-Human communication. None of its constructs will translate to actual code that the machine will see. Never the less documentation will be tightly integrated into the source code, because part of my design goals is to facilitate in code comprehension and code navigation.

How is documentation related to code comprehension is pretty straight forward. Most of use make use of tutorials before we start using a new library or platform. Why not allow the designer of those libraries to include a tutorial as part of his source code. Let the senior developer include a couple of diagrams as to how the data structures or APIs are structured.

Using documentation for code navigation is new and revolutionary. Most of us navigate code by opening a file manager, going thru the directories, opening and closing source files trying to find a lead or a clue that will help us. Some of us are bit more clever and use grep to do the searching. I find that approach archaic. The future I want to live in is one where you open the source code and you find diagrams that visually outline how the source code is organized. Then you click on parts of these diagrams to navigate different aspects of the source code until you find what you want. Hollywood style.

In the diagram above, its a case use for a team manager. Lets say you are a team manager and you want to audit someone's work. You pull up the smart-diagram of your team. You click on the person you want to audit. It runs a script that pulls up everything he worked on recently. Then you click on what you want to audit. That is code navigation like few of us have seen before.

The following are a set of constructs I am considering. I am borrowing some ideas from the web. I am not importing technologies from the web thou. I see it done all around me and I don’t like it. Apps these days are pretty much integrated web-browsers.

1) Hyper text: The idea to click on text and it brings up source code. Or vice versa. Clicking on a function call and it brings up related documentation. Rather then HTML, I will probably adopt a simpler format like markdown.

2) Smart Diagrams: This idea is the same as image maps in HTML. You have a picture or diagram and certain areas are clickable. This is how you would navigate source code.

3) Mind-Maps: This is to allow developers to brain storm and keep track of themselves and they proceed with their project. Also used to navigate code.

4) Document side scripting: serves a purpose similar to PHP, it allows for dynamic documentation. Documentation that updates itself as changes are made.

NOTE: constructs from lower layers will cooperate in creating self updating documentation. For example every time you create a variable or function, an entry is made in an internal database that keeps track of them. Depending on the changes certain documents will be automatically created and updated. Quick examples of this is a table of contents, an index table and a quick reference guide.

[kagenoneko]

I love reading about other areas of my field and what they are doing.

[vanguardparty]

A community for tech writers

Share ideas

Ask questions

Get extra eyes

Share tools

Rib product managers

Comisserate

Ideate

Incubate

Peer review

Share solutions

Grow a network

Invites: https://www.tumblr.com/join/bYNj2jMH

[sweaterkittensahoy]

SCREAMS IN TECH WRITER

PAGING @minim-calibre TO SCREAM WITH ME

ALL FELLOW TECH WRITERS WELCOME

YOU WROTE DOWN THAT YOU NEEDED TO DO IT AND THEN YOU SKIPPED IT YOU FUCKING ASSHOLES

[w1770w]

GUMROAD IS BANNING NSFW CONTENT IN THE NEXT 24 HOURS

I haven't seen anyone talk about this yet, so I might as well.

They've updated their content policy to comply with payment processor Stripe and Paypal's censorhip. They gave 24 hours. On March 16th 2024, Gumroad TOS will no longer allows sales of any written or drawn nsfw content.

This is going to hurt for so many creators. Giving that little time leaves people's source of income wildly unstable, especially with such a huge overhaul of what content is allowed.

I hate this. I hate what censorship is turning the internet into. I hate that nsfw content creators keeo getting pushed to the fringes, that they need to digitally migrate so often, because nowhere can be trusted to allow their art for long.

I don't know what to do next, there isn't some sort of "here's what you can do to help!" People just deserve to know.

[dnschmidt]

A shot of entendre, please. Make it a double.

At work, I was going through some machinery drawings and came across these notes explaining the design changes:

Shaft size increase

New part for bottom cavity

Oh really? 🤭

[fehck]

[technically-human]

i loved seeing the moment of stone realising he was going to stick with robotnik (─‿‿─) could we see the moment ROBOTNIK realises stone is here for good?

Robotnik isn't used to people being happy to see him

[talos-stims]

the computer blade | source