New series: A tech writer's guide to the Redocly galaxy
Here at Redocly, we want everyone to feel comfortable using our products. If you're new to open source, command lines, GitHub and docs-as-code, this series is for you!
A bit of background...
I'm Jody, a technical writer based in Auckland, New Zealand. I've been helping the team here at Redocly improve our open-source docs. Coming from a traditional tech writing background, at first I found it hard to get my head around the processes and concepts that make Redocly's products so amazing.
So, I decided to share my learning journey and help others get over that initial hump. I don't want anyone missing out just because they don't know their command lines from their pull requests!
Are you a tech writer who has always wondered about Redocly? Have you poked around our website then nervously closed your browser when you came across a term you didn't understand? Have you been tasked with streamlining and automating your company's API docs but have no idea where to start? Then read on!
Over the course of this series, I'll introduce you to some core concepts that will help you get the most out of our open-source tools: Redocly CLI and Redoc. These tools are free to use, and a fantastic place to start your docs-as-code journey. You can throw a couple of API reference docs at them, play around, and produce API docs so awesome, your organization will beg for more!
I recommend reading the entire series before you start installing and using our open-source products, so you have the confidence to get the most out of what are (in my humble opinion) some pretty cool tools.
Our first lesson? What is 'open source' and why you should care.
What is open-source software?
opensource.com nails this definition in a single sentence:
Open source software is software with source code that anyone can inspect, modify, and enhance.
In recent years, a huge worldwide open-source community has grown — one that values sharing, collaboration and learning. Even if you're not digging around in the codebase or contributing to the docs, by using Redocly's open-source products, you are part of the community.
Redocly offers both open-source and premium products to our customers, but we started out as purely open source! Our open-source products are:
- Redocly CLI (organizes and validates your API definitions).
- Redoc (publishes API docs onto a website).
I'll discuss Redocly CLI and Redoc in more detail later in this series, but first you need to get to grips with what we mean when we talk about 'API docs'. More about them in the next installment...