The hottest Documentation Substack posts right now

And their main takeaways
Category
Top Business Topics

Literate Testing

Rethinking Software • 99 implied HN points • 14 Jun 25
🕹 Technology Software Programming Testing Development Documentation
  1. Literate programming is great for keeping your code and documentation together. It helps you write tests in a clear and organized way without needing extra frameworks.
  2. With literate programming, you can easily mock functions and test them directly, even in languages like C that are usually tricky to test. This makes the testing process simpler and more enjoyable.
  3. Placing tests right next to your code helps you keep everything organized and makes writing tests feel less like a chore. You start to see tests as part of your coding process rather than an extra step.

Anatomy of Oscillation

Software Design: Tidy First? • 1060 implied HN points • 10 Feb 25
🕹 Technology Software Design Systems theory Documentation Agile development GenAI
  1. Oscillation occurs when systems swing between extremes, like adjusting a thermostat. A delay between making a change and feeling the effect can cause back-and-forth adjustments.
  2. In nature, predator and prey populations can also oscillate, like rabbits and hawks. More rabbits lead to more hawks, which eventually can cause the rabbit population to drop, repeating the cycle.
  3. Calls for comprehensive documentation in software may lead to oscillation. As information decays over time, teams might swing between needing more documentation and finding fewer resources to support that need.

6 Must Have Software Engineering Templates

High Growth Engineer • 2002 implied HN points • 02 Feb 25
🕹 Technology Software Development Productivity Documentation Templates
  1. Using templates can help software engineers write better documents quickly and effectively. They save time and improve communication.
  2. A good feedback template divides suggestions into categories, making feedback clearer and more constructive.
  3. Having a brag doc or weekly update template helps track progress and makes performance reviews easier.

Three Elements of a Good API README

The API Changelog • 4 implied HN points • 22 Feb 25
🕹 Technology APIs Documentation Software Development Tools
  1. A good API README should give a clear overview of what the API does. This helps users quickly understand its purpose and features.
  2. The 'Getting Started' section is important for guiding users on how to authenticate and make their first request. This ensures they can use the API without confusion.
  3. Lastly, include practical information about key operations in the API. Users should see examples and know where to find more detailed documentation for further help.

Self-documenting Makefiles

Blog System/5 • 827 implied HN points • 10 Jan 25
🕹 Technology Software Development Programming Documentation Open Source
  1. Using Makefiles can help stitch together complex build processes easily. They allow you to create a command dispatcher with minimal code.
  2. By implementing a 'make help' command, you can provide users with a clear overview of available actions and necessary configuration, reducing confusion.
  3. Documenting both targets and user-settable variables in Makefiles can make them more user-friendly. This helps users know how to interact with the project without getting lost.
Get a weekly roundup of the best Substack posts, by hacker news affinity:

Bad Software Advice: Three Interesting Links #6

Bad Software Advice • 164 implied HN points • 20 Jan 25
🕹 Technology Software AI Management Remote work Documentation
  1. Documentation is important, but sometimes people struggle to keep it updated. A funny story shared highlights a case of trying to restore missing documents in a company.
  2. Remote work has its advantages, but it doesn't fit everyone's situation. Personal circumstances can greatly affect how well someone can work from home, and it's important to consider different perspectives on this topic.
  3. Incompetent management can sometimes still keep a company afloat if conditions are stable. However, if situations change, it can threaten the organization's survival.

Be part of the solution, not part of the problem

Thái | Hacker | Kỹ sư tin tặc • 2256 implied HN points • 17 Oct 23
💼 Business Management Accountability Incident Response Communication Documentation
  1. Notify all stakeholders before making any production changes to avoid becoming part of the problem.
  2. Overcommunicate during a problem by sharing information to involve stakeholders in finding solutions.
  3. Make yourself accountable for mistakes to be a part of the solution and promote learning and improvement.

Making Science More Reproducible

Briefly Bio • 158 implied HN points • 18 Jul 24
🔬 Science Research Methodology Documentation Innovation
  1. Reproducibility in science is a big issue, with many experiments failing to be duplicated. This creates a challenge for scientists trying to build on each other's work.
  2. Clear and detailed documentation of scientific processes is crucial. When scientists share their methods well, it helps others replicate results more easily.
  3. Using technology like structured documentation can improve transparency in research. This way, scientists can better understand what happened in an experiment and learn from it.

How to lead projects from start to finish as a software engineer

High Growth Engineer • 1285 implied HN points • 10 Mar 24
🕹 Technology Software Engineering Project management Leadership Communication Documentation
  1. Successful software engineers need to know how to lead projects, not just code
  2. Key project management steps include kickoff, setup, planning, execution, launch, and close-out
  3. Communication, alignment on goals, and iterative feedback are crucial throughout the project lifecycle

The short outburst of activity during Ruby Changelog preparation—2025 edition

zverok on lucid code • 28 implied HN points • 06 Jan 25
🕹 Technology Programming Software Development Documentation Language
  1. Ruby releases a new version every year on December 25th. This has been consistent since 2013, which makes it easier for developers to plan their updates.
  2. A changelog is created that details all the noteworthy changes in the Ruby language. This includes explanations and examples to help developers understand the updates better.
  3. The changelog process helps improve Ruby's documentation and sometimes identifies issues that need to be fixed before the new version is released.

Simple tricks to level up your technical design docs in 2024 👌

High Growth Engineer • 1108 implied HN points • 28 Jan 24
🕹 Technology Career development Documentation Software Engineering Feedback
  1. Design docs help to reduce risk, document decisions, and align on technical choices.
  2. Make design docs concise with only essential information for decision-making to ensure they get read and progress smoothly.
  3. Get individual feedback first before group sessions to make the review process more efficient and effective.

The loneliness of the long distance runbook

Wednesday Wisdom • 56 implied HN points • 11 Dec 24
🕹 Technology Software Engineering Documentation Management Processes
  1. Runbooks are often not followed closely because experienced engineers adapt them to their own knowledge and context. This can be good, but it also means runbooks might not be used as intended.
  2. When runbooks have errors or are not up to date, they can cause big problems. It's crucial to review and update runbooks regularly to keep them relevant and accurate.
  3. Don't expect runbooks to be perfect or solve all issues. They should be seen as guidelines rather than strict instructions, and everyone should have an understanding of the system behind them.

Documentation-driven API Design

The API Changelog • 6 implied HN points • 24 Jan 25
🕹 Technology API design AI Tools Documentation Software Development
  1. You can create an API by simply writing down what you want it to do, and AI can help turn that into a working API document. It's as easy as writing a description and letting the technology handle the rest.
  2. Using AI tools like ChatGPT, you can get detailed how-to guides for your API based on a simple description, making it easier to understand how to use it.
  3. By generating an OpenAPI document from your description, you can quickly set up a mock API server, allowing you to test and get feedback on your API design in no time.

How I Use AI

Jobs For AI • 26 HN points • 07 Jul 24
🕹 Technology AI Search Documentation Writing
  1. Using AI for writing code can save time and automate tasks, especially for novice programmers
  2. AI can enhance search capabilities and help in learning by providing concise information and alternatives
  3. AI can assist in documentation tasks, like generating instruction documents, and improve writing tasks such as composing sales emails

"Organic Markdown" Intro

Rethinking Software • 199 implied HN points • 21 Aug 24
🕹 Technology Programming Software Development Documentation Open Source
  1. Organic Markdown helps keep your code and documentation in sync. This means you won't have to edit your code separately from your notes, making everything easier to manage.
  2. It improves how your code is presented. By arranging your code better for people to understand, you can still adjust it later for the computer to run.
  3. You can run commands and build applications right from your Markdown file. This makes the workflow smoother and lets you focus more on coding.

Bernie & G.: a life in photos, before Stonewall

well, actually • 196 implied HN points • 22 Feb 23
🎭️ Culture LGBTQ+ Photography History Documentation
  1. The photo album documents a gay couple's life before Stonewall, showcasing rich moments of love and connection.
  2. Queer life in mid-20th century US was marked by oppression, but also contained joy, community, and individuality in private spaces.
  3. The album sheds light on Bernie and G.'s world, showing their private celebrations, travels, and relationships with friends and family.

How Nigeria Elected a Criminal as Its President: Part I

Aaron Greenspan • 369 implied HN points • 08 Dec 23
🌍 World Politics Corruption Elections Investigation Justice System Documentation
  1. Bola Tinubu, the President of Nigeria, has a controversial past involving money laundering and drug trafficking in the US.
  2. Despite his controversies, Tinubu's questionable history did not prevent him from becoming the President of Nigeria.
  3. Attempts to uncover more information about Tinubu's past through FOIA requests and lawsuits faced challenges and government denial.

The Joy of Literate Programming

Rethinking Software • 99 implied HN points • 02 Sep 24
🕹 Technology Programming Software Documentation Development Coding
  1. Literate programming is a fun way to write and document code. It's like mixing storytelling with coding, making the process more enjoyable.
  2. Using tools like Organic Markdown, you can easily manage and run code alongside your documentation in a Markdown editor. It helps keep everything organized and readable.
  3. This programming style allows for creative flexibility, like rearranging sections of code for better clarity and using command outputs as if they were code. It feels almost magical!

Ensemble Weather Forecast API

Open-Meteo • 351 implied HN points • 05 Jun 23
🕹 Technology Weather API Forecasting Models Documentation
  1. Ensemble weather forecasts show a range of possibilities, helping to understand the uncertainty in predictions.
  2. Weather forecasts differ in reliability based on location and weather patterns, affecting the level of uncertainty in predictions.
  3. The Ensemble API combines various weather models, providing access to different weather variables for various purposes.

Racket: The Lisp for the modern day

Deus In Machina • 326 implied HN points • 29 Jun 23
🕹 Technology Programming Languages IDE Documentation
  1. Racket is an advanced modern Lisp with a wide range of features and tools for developers in 2023.
  2. Racket is especially great for beginners, young programmers, and academics due to its simplicity, built-in IDE, and gradual learning curve.
  3. Racket's unique language building capabilities allow for creating domain-specific languages, documentation languages, and more, making it a versatile and powerful tool for programmers.

Producer-Oriented API Documentation

The API Changelog • 3 implied HN points • 10 Jan 25
🕹 Technology APIs Documentation Development Producers Consumers
  1. Good API documentation is very important for user experience. It helps consumers understand how to use the API effectively.
  2. Producers should use the documentation to see metrics about their API's performance. This helps them make better decisions about improvements.
  3. Sharing some API usage data with consumers could enhance transparency and build trust. It allows users to see popular features and error rates.

More than 30 unique tracking events will cause you problems

timo's substack • 78 implied HN points • 12 Feb 23
🕹 Technology Data Tracking Data Quality Data Analysis Documentation
  1. Having more than 30 unique tracking events can lead to problems in data adoption and productivity.
  2. Too many unique events can lead to difficulties in analyst productivity and data exploration.
  3. Implementing a lean event approach with a focus on good event design and ownership can help prevent issues caused by high event volumes.

Tales from the jar side: Uncensored Java AI, Pirate audio in text messages, LangChain4J used my video 😀, and the usual tweets and toots

Tales from the jar side • 39 implied HN points • 04 Feb 24
🕹 Technology AI Programming Audio Documentation Reviews
  1. A Java project called the Ollama project allows you to run uncensored AI models locally, without sending data offsite.
  2. An application was created to generate pirate insults in audio files using the Twilio API and Text-to-Speech capability of OpenAI.
  3. LangChain4J, a competitor to Spring AI project, now has a website with tutorials, including a video featuring Ken Kousen.

Unpacking Okta's Tech Architecture | Monica Bajaj - VP Developer Experience & Mark T. Voelker - VP Architecture at Okta

platocommunity • 39 implied HN points • 01 Feb 24
🕹 Technology Architecture Engineering Tech stack Scaling Documentation
  1. Okta believes in leveling up both the tech stack and the people stack for successful architecture.
  2. The Architecture Charter at Okta involves setting clear guardrails and handholds to empower engineers to make informed decisions.
  3. Writing things down, utilizing frameworks like RFCs and Requests for Discussion, is crucial for communication and knowledge sharing in the organization.

API Documentation for Machines

The API Changelog • 6 implied HN points • 22 Nov 24
🕹 Technology AI APIs Documentation Development Software
  1. API documentation should be structured and easy for machines to read. Using known formats like OpenAPI helps AI agents understand the API better, making it easier for them to use.
  2. Clearly define all operations and parameters in the documentation. AI agents need specifics about input types and constraints to avoid confusion.
  3. It's important to document errors and provide examples. Even machines need clear guidance on what each error means to function properly.

The making of Ruby Changes: A boring advent

zverok on lucid code • 86 implied HN points • 28 Dec 23
🕹 Technology Programming Software Development Language Evolution Documentation
  1. The author has been writing in Ruby for almost 20 years and started the Ruby Changes project to understand language evolution.
  2. The author experimented with an 'advent-style' approach to working on the changelog for Ruby 3.3, documenting the process daily.
  3. The diary of working on the Ruby changelog involved tasks like writing the changelog, addressing bugs, improving documentation, and reflecting on the language changes.

Advent of Ruby Changelog: Week 1

zverok on lucid code • 86 implied HN points • 07 Dec 23
🕹 Technology Programming Software Diary Documentation Ruby
  1. Preparing Ruby 3.3's annotated changelog involves detailed explanations of features, testing on new versions, and fixing documentation.
  2. Efficiently tracking new features and discussions for Ruby updates is crucial for the changelog process.
  3. A day-by-day diary format for working on the changelog helps in organizing thoughts and content for weekly round-up posts.

How to do developer marketing that doesn’t suck

Developer GTM – by Calyx Consulting • 59 implied HN points • 24 Aug 23
💼 Business Marketing Documentation Content Technology Audience
  1. Good developer marketing copy should be concise, use language that resonates with the target audience, and focus on addressing their pain points.
  2. Even if your company doesn't have an official marketing team, you are still doing marketing through how you present your brand and product to the world.
  3. In developer products, it's crucial to have a strong product first before attempting to out-market with weak marketing strategies.

Google Cloud's Core Principles of System Design [System Design sundays]

Technology Made Simple • 59 implied HN points • 04 Sep 23
🕹 Technology System Design Cloud Computing Documentation Architecture
  1. A robust system design should be secure, reliable, scalable, and independent, allowing for iterative changes without disruption.
  2. Document everything to help visualize deployments, collaborate effectively, and guide future design decisions.
  3. Simplify system design, use fully managed services, decouple architecture, and strive for a stateless architecture to improve reliability and scalability.

How Writing has helped me- even though it's failed [Storytime Saturdays]

Technology Made Simple • 59 implied HN points • 28 May 23
🚌 Education Writing Learning Communication Documentation Personal Development
  1. Creating content can provide exposure and opportunities, leading to networking and industry insights.
  2. Content creation can enhance learning by fostering a continuous search for knowledge and interactions with followers.
  3. Crafting content improves communication skills, critical thinking, and documentation, which can have a positive impact on personal and professional growth.

My Markdown personal management system

normality’s Substack • 3 HN points • 25 Jul 24
🕹 Technology Software Productivity Management Documentation
  1. This personal management system uses plain text in Markdown format, making it easy to use and modify. You can adjust it to suit your own workflow without getting overwhelmed.
  2. It provides flexibility while still offering helpful structure, so you can prioritize your tasks effectively. You can customize it to include sections for today, this week, and even future tasks.
  3. Though it's a personal tool, it can help you keep track of your projects and milestones. You can also use it to document completed tasks, which can be handy for remembering what you’ve accomplished.

Creating a Security Posture Report for a Specific Azure Subscription

Rod’s Blog • 19 implied HN points • 13 Feb 24
🕹 Technology Cloud Computing Cybersecurity Data Analysis Documentation
  1. Creating a security posture report for a specific Azure subscription provides enhanced visibility into the security state of assets and workloads, aiding in identifying potential vulnerabilities.
  2. The report includes guidance for improvement with hardening recommendations to help efficiently enhance security posture.
  3. Azure Secure Score assists in prioritizing security recommendations for effective triage to enhance security posture and align with compliance standards.