Introduction
I was scrolling through the internet one day and came across articles and guides on DEV Community and Hashnode. I got curious—who writes these kinds of articles? That's when I discovered that the people behind them are called technical writers.
Inspired, I started writing my own articles. My first article was about JavaScript while I was still learning it. At that time, I relied heavily on AI to write my articles. I would simply give it a prompt and publish the result. After a while, I realized that wasn't helping me learn or improve as a writer, so I decided to change the way I approached technical writing.
While looking for places to learn, I found the Hackmamba community. I started joining their coffee chats, where I got to hear experienced technical writers share their journeys and advice. Later, I joined Tom Johnson's API Technical Writing Sprint , and that's where my perspective on technical writing completely changed.
Until then, I thought technical writing was mostly about writing blog posts. The sprint showed me that it's much more than that. It involves documenting APIs, writing developer guides, collaborating on documentation, and helping developers understand products through clear and useful documentation.
As I explored this field further, I also discovered several tools that made different parts of the process easier. Some help me organize ideas before writing, some introduced me to API documentation, and others help me review and improve my work. In this article, I'll share the tools that have shaped my technical writing journey and what I learned from using them.
2. Obsidian — Where Every Article Begins
When I decided to take technical writing seriously, I started researching how experienced technical writers planned and managed their work. During that search, I discovered Obsidian, and it quickly became one of my favorite tools.
Today, almost every article I write begins in Obsidian. Whether it's brainstorming ideas, planning an outline, taking learning notes, or writing multiple drafts, everything lives in one place. Instead of switching between different apps, I can focus on writing without distractions.
What I appreciate most about Obsidian is its simplicity. It's just me, Markdown, and my thoughts. As I started writing more consistently, it helped me stay organized and significantly improved my writing workflow.
If you're planning to get started with technical writing, I'd definitely recommend giving Obsidian a try.
Quick Start
If you've never used Obsidian before, here's how you can get started in just a few minutes.
1. Create a Vault
After installing Obsidian, click Create New Vault, give it a name (for example, Technical Writing), and choose a location where all your notes will be stored.
📸 Obsidian Dashboard
2. Create Your First Note
Click New Note and start writing. I usually create separate notes for article ideas, research, and drafts. Since Obsidian uses Markdown, writing and formatting content feels simple and distraction-free.
3. Organize Your Notes
As my writing grew, I started organizing everything into dedicated folders. Here's how I currently structure my vault:
- Articles Draft – Articles I'm actively writing.
- Articles Rough – Rough ideas and unfinished drafts.
- Final Articles – Completed articles ready to publish or already published.
- Code Snippets – Reusable code examples for future articles.
- Visual Library – Images, diagrams, and illustrations used in articles.
- Assets – Supporting files and resources.
This structure helps me quickly find what I'm looking for without searching through dozens of notes.
📸 My Obsidian Folder Structure
4. Draft Your Articles
Once my research and outline are ready, I start writing the article in Markdown. I usually create multiple drafts before publishing. Having everything—from the first idea to the final draft—in the same vault makes the entire writing process much smoother.
📸 Sample Article Draft
Why I Recommend Obsidian
For me, Obsidian is more than just a note-taking app—it's where every article begins. It has helped me organize my ideas, manage multiple drafts, and build a writing workflow that keeps me focused on learning and creating instead of searching through scattered notes.
If you're starting your technical writing journey, Obsidian is a tool that's definitely worth exploring.
Once I had a writing workflow, I became curious about another side of technical writing that I'd never explored before—API documentation.
3. Stoplight — My Introduction to API Documentation
After joining the Hackmamba community, they announced Tom Johnson's API Technical Writing Sprint. Until then, I only knew about writing technical articles and blogs. API documentation was completely new to me, so I started exploring what it actually was.
While following the sprint, I discovered Stoplight. What I liked most about it was that I didn't need to know YAML to get started. Instead of writing an OpenAPI specification from scratch, Stoplight provides a visual interface where you can fill in details like endpoints, parameters, responses, and descriptions. At the same time, it automatically generates the OpenAPI YAML file in the background.
As someone who had never worked with OpenAPI before, this made learning API documentation much easier. Instead of worrying about YAML syntax, I could focus on understanding how API documentation is structured.
Quick Start
If you're new to Stoplight, here's how you can create your first API documentation project.
1. Create a Workspace
Create a new workspace and start a new API project. This is where you'll design and organize your API documentation.
📸 Stoplight Dashboard
2. Add an Endpoint
Create an endpoint by specifying the HTTP method, path, parameters, request body, and responses. The visual editor makes it easy to fill in these details without manually writing YAML.
📸 Visual API Editor
As you add information through the interface, Stoplight automatically generates the corresponding OpenAPI YAML specification.
📸 Generated YAML
3. Preview the Documentation
Once your endpoint is complete, preview the generated documentation to see how it will look to developers using your API.
📸 Documentation Preview
What I Learned
Stoplight changed the way I looked at API documentation. Before using it, I thought documentation was only about writing explanations. After exploring Stoplight, I realized that good API documentation is also about structure, consistency, and making information easy for developers to understand. It became my first step into the world of OpenAPI and API documentation.
After learning the basics with Stoplight, I wanted to understand how larger OpenAPI projects are organized and maintained.
4. Redocly — Making OpenAPI Projects Easier to Manage
After learning the basics of OpenAPI with Stoplight, I started exploring Redocly CLI.
The first feature that stood out to me was the split command. Instead of keeping the entire OpenAPI specification in a single YAML file, Redocly organizes it into smaller files like paths, schemas, parameters, and security schemes. I found this much easier to navigate than working with one large file.
Another feature I found useful was redocly lint. YAML files are easy to break with small mistakes, so having a command that checks the entire specification before generating the documentation was really helpful. It saves time and makes it easier to catch errors.
I also used preview-docs to view the documentation locally before publishing it. Being able to make changes and immediately see the result made the workflow much smoother.
What I liked most about Redocly is that it makes OpenAPI projects easier to organize and maintain. I can see why teams working on larger APIs would prefer this approach instead of keeping everything in one file.
Quick Start
1. Install Redocly CLI
npm install -g @redocly/cli@latest
2. Split Your OpenAPI File
If your OpenAPI file starts getting large, you can split it into smaller files.
redocly split openapi_openweathermap.yml --outDir openapi
Here's how the project looks after splitting:
redocly_project
├── openapi
│ ├── components
│ ├── paths
│ └── openapi.yml
└── openapi_openweathermap.yml
📸 Splitting the OpenAPI file
3. Lint Your Specification
Run:
redocly lint
This command checks your OpenAPI specification for errors and common issues before you generate documentation.
📸 Running lint
4. Preview Your Documentation
Once everything looks good, preview your documentation locally.
npx @redocly/cli preview
📸 Generating the preview
5. Open It in Your Browser
Redocly starts a local server where you can see exactly how your documentation will look.
📸 Browser Preview
What I Learned
Before exploring Redocly, I thought API documentation was mostly about writing YAML files. After using it, I realized that's only one part of the process. Organizing files, validating the specification, and previewing the final documentation are just as important. That gave me a much better understanding of how documentation is managed in real-world projects.
Learning how to write documentation was one thing. I also wanted to understand how documentation is maintained once people start contributing to it.
5. GitHub — Documentation is a Collaborative Process
Before contributing to documentation, I mostly used GitHub to host my projects. Once I started contributing to open source documentation, I realized that documentation goes through the same collaborative process as code.
Every documentation change starts with a branch and a Pull Request. Maintainers review your work, leave comments if something needs to be improved, and once everything looks good, they merge it.
One thing I really liked was that everything happened in one place. I could discuss changes, update my Pull Request, respond to review comments, and keep track of every revision.
I also learned that contributing to documentation isn't only about writing new pages. You can fix typos, improve tutorials, update examples, write how-to guides, or even help with localization. There are many ways to contribute, even if you're just getting started.
For me, GitHub made documentation feel much less intimidating because I realized that reviews and feedback are a normal part of the writing process.
Quick Start
1. Find Your First Documentation Issue
If you're not sure where to start, GitHub's Advanced Search is a great place to find documentation issues across open source projects.
You can search using labels like:
documentationgood first issue
These labels usually point to beginner-friendly issues.
📸 GitHub Advanced Search
After searching, you'll find documentation issues from many different projects.
📸 Search Results
Pick a project that interests you and read its contribution guidelines before making any changes.
2. Fork the Repository
Once you've found an issue you'd like to work on, click Fork.
This creates your own copy of the repository where you can make changes safely without affecting the original project.
📸 Forking the Repository
3. Create a New Branch
Before making any changes, create a new branch for your documentation contribution.
git checkout -b improve-api-guide
Using a separate branch keeps each contribution organized and makes it easier to review.
4. Make Your Changes
Update the documentation, save your changes, and commit them.
git add .
git commit -m "docs: improve API setup guide"
Push your branch to your fork.
git push origin improve-api-guide
5. Open a Pull Request
Go back to GitHub and click Compare & Pull Request.
Write a short description explaining what you changed. I usually mention the issue number and briefly describe the changes so reviewers know what the Pull Request is about.
📸 Opening a Pull Request
6. Respond to Review Feedback
Getting review comments is completely normal. My documentation Pull Requests also received feedback.
Read the comments carefully, make the requested changes, commit them, and push again. GitHub automatically updates the same Pull Request with your latest changes.
📸 Review Comments
7. Celebrate the Merge 🎉
Once the maintainers are happy with the changes, your Pull Request gets merged into the project.
📸 Merged Pull Request
What I Learned
GitHub taught me that documentation isn't something you write alone. It improves through discussions, reviews, and feedback from other contributors. Every Pull Request helped me become a better technical writer while also giving me a better understanding of how documentation is maintained in open source.
While these tools improved my documentation workflow, one tool completely changed how I approached writing itself.
6. AI — How My Workflow Changed
When I started writing technical articles, I relied on AI far more than I should have.
I'd ask it to write an article, copy the response, take the screenshots it suggested, and publish it. I wasn't doing much research, writing drafts, or even thinking deeply about the topic myself.
After a while, it didn't feel right.
I realized I was publishing articles, but I wasn't becoming a better developer or a better writer.
That completely changed how I use AI today.
Now, every article starts with my own thoughts. I brainstorm ideas, do my research, write rough drafts in Obsidian, and build the structure myself.
Only after that do I use AI.
Today, AI helps me with things like:
- Improving grammar and readability.
- Reviewing the overall flow of an article.
- Brainstorming better titles.
- Challenging my understanding of a topic.
- Pointing out gaps that I should research further.
One thing I find especially useful is asking AI to question my ideas instead of asking it to answer them.
When I have an article idea, I'll explain it to AI and ask it to challenge my understanding. Sometimes it asks questions I can't answer immediately. That's usually a sign that I need to go back, research more, and understand the topic better before writing about it.
The biggest difference is that AI no longer writes my articles. It helps me review and improve the ones I've already written.
Before vs. Now
How I Used AI Before
When I first started writing, I relied heavily on AI to generate the content. I would make only small edits before publishing, without spending much time researching or writing the draft myself.
📖 Example:
Deploy Your Web Application on Vercel Quickly
📸 One of my earlier articles
How I Use AI Today
My workflow looks very different now.
- Learn the topic.
- Build a project or experiment.
- Research using documentation and other reliable resources.
- Write the first draft in Obsidian.
- Ask AI to review, question, and improve the draft.
- Edit the article myself before publishing.
The article below reflects that workflow. The ideas and experiences came from building the project, while AI helped me refine the writing, question my assumptions, and improve the overall clarity.
📖 Example:
What I Learned Integrating AI into My React App
📸 A more recent article
What I Learned
Looking back, the biggest change wasn't learning how to use AI—it was learning when to use it.
Today, AI helps me review, question, and refine my work, but the ideas, research, experiments, and experiences still come from me.
That shift has made writing much more enjoyable because every article teaches me something new instead of simply helping me publish faster.
7. What These Tools Taught Me
Looking back, every tool taught me something different. They weren't just tools—they changed the way I think about technical writing.
Obsidian taught me that writing starts long before publishing. It's where I brainstorm ideas, plan outlines, write multiple drafts, and keep everything organized in one place. For me, it has become the center of my writing workflow.
Stoplight showed me that I didn't need to know OpenAPI or YAML to start learning API documentation. Its visual editor helped me focus on understanding the structure of an API instead of worrying about syntax.
Redocly taught me how larger OpenAPI projects are managed. Features like splitting large specifications and linting made me realize that writing the documentation is only one part of the process—maintaining it is just as important.
GitHub helped me understand how documentation is built in open source. Through Pull Requests and reviews, I experienced how documentation improves through collaboration instead of being written by one person.
AI completely changed my workflow. Instead of asking it to write articles for me, I now use it to review my work, question my understanding, and help me improve what I've already written.
Together, these tools helped me realize that technical writing is much more than writing articles—it's about creating a workflow that helps you learn, document, collaborate, and continuously improve.
8. Key Takeaways
If there's anything I'd like you to take away from this article, it's these three lessons:
Use AI to improve your thinking, not replace it. The biggest change in my workflow happened when I stopped asking AI to write articles and started asking it to challenge my understanding.
Contribute to open source as early as you can. Reading documentation and watching tutorials teaches the basics, but contributing to real projects teaches you how documentation is actually written, reviewed, and maintained.
Find a workflow that works for you. There are many great tools available, but Obsidian has become an important part of my writing process because it keeps everything—from ideas to final drafts—in one place without distractions.
9. Conclusion
When I first discovered technical writing, I thought it was simply about writing technical blog posts.
After joining communities like Hackmamba and participating in the API Technical Writing Sprint, I realized it's much bigger than that.
Technical writing includes API documentation, developer guides, product documentation, collaboration through GitHub, reviewing Pull Requests, maintaining documentation, and making products easier for developers to understand.
This journey taught me that becoming a better technical writer isn't about collecting more tools. It's about understanding the product, doing the research, and communicating ideas clearly. The right tools simply make that process easier.
I'm still early in my technical writing journey, and there's a lot more I want to explore. Next, I'm curious about tools like Mintlify, Document360, and how AI and agent documentation are shaping the future of developer documentation.
If you have a favorite tool or resource that helped you become a better technical writer, I'd love to hear about it.
Resources That Helped Me
If you'd like to explore technical writing or API documentation, these are some of the resources I found most helpful.
📖 Tom Johnson's API Documentation Course — A great starting point for learning API documentation.
📝 Obsidian — My go-to tool for brainstorming, outlining, and drafting articles.
📚 GitHub Advanced Search — Useful for finding beginner-friendly documentation issues in open source.
🎨 OG Image Generator — Helps me create cover images for my articles.
Top comments (0)