does anyone have good resources on (accessible) technical writing?

feel like i suck at this, just getting bogged down in details when there's mountains of unexplained prior knowledge that might be more important..

:boost_requested: :boost_ok:

I also published this old unfinished writing project of mine (2020), where I tried to explain internals of this project before. Let me know what you think

cthu.lu/projects/react-hooks-s

Follow

@f0x What is the intended audience ? I thought it was fairly well written and easy-enough to understand, but also I've done a lot with react -- I bet someone who has never used react before would be slightly lost if they read it.

Regarding the part where it shows the normal react useEffect component and then describes what that code is doing -- I think it might be easier for folks who are new to react if it mentioned that in order to understand the next section, you probably need to understand react function components. Then it can offer a link to a primer on React function components and another link to a primer on useEffect.

When you get into explaining what the code does line by line, I think it might help to show the whole code block first, then go through it again line by line or section by section alternating between sections of the code block and explanation text.

(right now its just code block, then one big block of explanation text. By breaking the code and explanation into smaller chunks it reduces the amount of working memory that the reader has to allocate in order to understand what you wrote)

When you mention stuff offhand like the normal useEffect function interface specifying that any return value should be a cleanup function, I think it might be good to hyperlink that part to the docs that describe the spec and/or to an example code block that shows what that looks like. I didn't even know that this cleanup function return value existed! So I would have been delighted to click "open in new tab" on it and read more.

This isn't based on any theory of technical writing or anything I guess its just my 2c.

I never studied technical writing formally, but in my opinion if you study any form of writing like written journalism or creative writing, it will help your technical writing a lot too! When I was in college I took a lot of creative writing classes and I think those helped me considerably.

· · Web · 0 · 0 · 1
Sign in to participate in the conversation
Pixietown

Small server part of the pixie.town infrastructure. Registration is approval-based, and will probably only accept people I know elsewhere or with good motivation.