Top all-time · #7872
Stoplight
Company blog · blog.stoplight.ioprogrammingweb
Stoplight is the company blog at blog.stoplight.io, writing about programming and web. Since 2015, 9 different Hacker News readers have linked it 30 times, most often “The Evolution of API Documentation at Stoplight”. It is still writing: the last post was on 2026-08-14, and you can follow it by feed.
Too few sampled comments (1) to say how often HN recommends it.?
Why HN links it
HN readers link Stoplight's posts on writing documentation for non-technical writers, mainly API documentation. One commenter links a part 2 and suggests an overview/intent section that the articles lack.
Summarised by Claude from a sample of 1 HN comments that link here. Each comment is marked recommending, critical or neutral (citing without judging); how this works.
Get tips and tricks for building APIs at any scale using the design-first approach.
Most-linked posts?
- The Evolution of API Documentation at Stoplight3 people · 3 mentions · first linked 2018-09-19
- Stop Calling Your APIs Microservices2 people · 2 mentions · first linked 2018-12-04
- APIs from a Beginner2 people · 2 mentions · first linked 2017-08-15
- OpenAPI and Design-First Principles2 people · 2 mentions · first linked 2018-06-21
What Hacker News says?
Great articles (there is a part 2 here: https://blog.stoplight.io/writing-documentation-when-you-are... ) The article is about API documentation, but the points apply to every documentation. I think however that a few things are missing in the articles: 1- an OVERVIEW/INTENT page/paragraph. This is THE thing that is missing in almost every -if not all- documentation I've ever read. An example that I always use to il…
Comment linking /writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a?source=collection_home---1------0----------------
on “Writing Documentation When You Aren't a Technical Writer”Submitted Writing Documentation When You Aren't a Technical Writer as a story · 303 points
HN discussionSubmitted Writing Documentation When You Aren't a Technical Writer – Part Two as a story · 125 points
HN discussionSubmitted Aligning on Your API Design Using Jobs to Be Done as a story · 52 points
HN discussionSubmitted The evolution of JavaScript functions as a story · 9 points
HN discussionSubmitted Fundamentals of HTTP API Unit Testing as a story · 6 points
HN discussionSubmitted Best Visual Rest API Editor as a story · 6 points
HN discussionSubmitted Writing Documentation When You Aren't a Technical Writer – Part Two as a story · 4 points
HN discussionSubmitted Stop Calling Your APIs Microservices as a story · 3 points
HN discussionSubmitted Stop Calling Your APIs Microservices as a story · 3 points
HN discussionSubmitted Making the Most of Your API Specification as a story · 3 points
HN discussionSubmitted OpenAPI and Design-First Principles as a story · 3 points
HN discussionSubmitted APIs from a Beginner as a story · 3 points
HN discussionSubmitted Components of Killer API Docs – Stoplight API Corner as a story · 3 points
HN discussionSubmitted API-first vs. API design-first as a story · 2 points
HN discussionSubmitted Powering API Governance with Spectral as a story · 2 points
HN discussionSubmitted The Evolution of API Documentation at Stoplight as a story · 2 points
HN discussionSubmitted The Evolution of API Documentation at Stoplight as a story · 2 points
HN discussionSubmitted Writing Documentation When You Aren't a Technical Writer – Part Two as a story · 2 points
HN discussionSubmitted Stoplight v4.0.0 – Realtime, Editor Toolbar, OpenAPI Read Mode as a story · 2 points
HN discussionSubmitted Spectral Governance for Arazzo and API Workflows as a story · 1 points
HN discussionSubmitted Stoplight Joins SmartBear: A CTO Perspective as a story · 1 points
HN discussionSubmitted Making the Most of Your API Specification as a story · 1 points
HN discussionSubmitted The Evolution of API Documentation at Stoplight as a story · 1 points
HN discussionSubmitted Want People to Use Your API Documentation? 5 Expert Tips as a story · 1 points
HN discussionSubmitted OpenAPI and Design-First Principles as a story · 1 points
HN discussionSubmitted Induced Logic Puzzles: Rhyme of the Ancient Engineer as a story · 1 points
HN discussionSubmitted The API Cornucopia as a story · 1 points
HN discussionSubmitted Restful APIs Achieving Quick and Easy Service Virtualization as a story · 1 points
HN discussionSubmitted Automate Swagger / RAML / JSON Schema Generation with New API Discovery Tool as a story · 1 points
HN discussion