How I Write My Articles
I guess this post is here for aspiring technical writers or technical bloggers who want to understand my process for writing an article. This will mostly be tailored towards people who want to write about Rust, but you can apply this to whatever you wanna write about.
The process goes roughly something like this:
- Think of an idea
- Do deep research into GitHub repos, Zulip/Discord discussions and reading some source & example code
- Write a mini-project that uses said thing
- Do an outline of the article detailing all of the major points I need to hit
- Flesh out the article
- Add any pictures where necessary
- Send it
Step 2 is arguably the most important part. As a technical writer (or blogger!), you are expected to be seen as a subject matter expert in what you're talking about. Within the Functional Programming community, this is particularly relevant - if something is wrong, people will absolutely tell you about it. As someone who posts articles week in week out about Rust for a Rust-based startup, it's a lot to bear. On the other hand, they're also doing it for the right reasons: they want the ecosystem to be of high quality. I can't say I blame them.
This is mostly to say that certain popular programming languages have a huge amount of articles by junior developers on fundamental concepts, who generally post on Hashnode or Dev.to (or Medium). I don't think this is wrong: the fundamental reason why so many junior devs are doing this is to showcase their skills, and it also helps pad their CV/resume. The tech industry is hard enough as it is - so doing anything you can to stand out is a good thing. From my experience though, this also makes it difficult to cut through the noise and find high quality articles within the JS ecosystem.
It would be safe to say that in the FP community, this doesn't wash - at the very least, you have to be adding some kind of value by providing something of value that goes beyond what the basic documentation says. For example, if you're writing an article about Kafka with Rust - you should try to learn about using Kafka outside of Rust. What are the pitfalls? How can you re-implement certain techniques (at-least-once delivery for example) using rust-rdkafka? I cannot stress enough the importance of knowing the information inside and out - if you're not sure if something's right or not, consult the documentation or mock up a project and try stuff.
Having a strategy for learning crates/libraries quickly is also really, really important. Here's my list of to-dos when looking at a crate:
- If the crate has any tutorials, read them and assimilate the learnings
- Check out the examples
- Check out the GitHub issues/PRs and make note of any specific issues
- Check any Rust-related Discord groups I'm in to see if anyone's mentioned the crate
- Check out chats for the related crate if there are any
- If the crate is related to a third party service or infrastructure, learn about how it's used outside of Rust
- Check the Rust subreddit to see if anyone's talked about it
- Make notes on all of the above
This is by no means an exhaustive list of things you should do, but I believe it covers most use cases well enough that you can write relatively well about most crates once you've done all of it.
The next two principles are also key to writing good articles:
- Don't write things that are blatantly wrong
- Proof-read your work
Both of these are important, but the first one is far more important than the second one. Proof-reading your work is important because it makes it more readable. However, if you're writing things that are wrong or otherwise not truthy, people may then take away the wrong thing from your article. That's not good.
Some tools you can use to proof-read:
- Grammarly
- Hemingwayapp (would highly recommend)
That's pretty much it from me. Thanks for reading!