The hottest Documentation Substack posts right now

And their main takeaways
Category
Top Business Topics

Why aren't AI productivity gains higher?

Engineering Enablement • 18 implied HN points • 19 Mar 26
🕹 Technology Documentation
  1. AI does make writing code faster, but coding is only a small part of an engineer’s work, so those speedups only move the overall output a little.
  2. Speeding up code creation exposes or creates downstream bottlenecks — things like code reviews, validation, and handoffs haven’t kept up, so saved time often gets consumed later.
  3. Adoption and impact are limited by social friction, immature tools, skill gaps, and missing implicit context in codebases, so real gains require better workflows, documentation, and team alignment.

Claude Code’s Secret Weapon: The Complete Guide to CLAUDE.md, SKILL.md & Every Important File You’re Ignoring (+ 60 Copy-Paste Templates)

The Product Channel By Sid Saladi • 37 implied HN points • 06 Mar 26
🕹 Technology Documentation
  1. Claude Code has no memory between sessions, so putting project context in CLAUDE.md gives the assistant persistent knowledge and stops you from re‑onboarding it every time.
  2. The .claude folder (settings.json, rules/, skills/, agents/, etc.) plus a global ~/.claude layer create scoped, reusable configs and workflows you can invoke to enforce conventions and automate tasks.
  3. Writing clear CLAUDE.md, SKILL.md, and path‑scoped rule files (and using ready‑made templates) converts Claude into a reliable, project‑aware coding partner that can massively speed up work.

How I code going into 2026

Olshansky's Newsletter • 183 implied HN points • 05 Jan 26
🕹 Technology Documentation
  1. Most coding is now delegated to AI agents, so engineers spend their time orchestrating agent personalities and guiding work rather than writing code by hand.
  2. Practical workflows matter: use Makefiles as a stable CLI, leave TODOs instead of side quests, maintain prompts/skills, write short copy-paste friendly docs, and review critical diffs on GitHub.
  3. Team roles and skills are shifting: leaders must be hands-on translators of intent into agent-driven work, focusing on system design, taste, and continuously improving agent behavior.

Unix Review Interviews Ted Dolotta and Heinz Lycklama from Interactive Systems Corporation (1984)

Computer Ads from the Past • 256 implied HN points • 28 Nov 25
🕹 Technology Documentation
  1. PC/IX is a faithful port of AT&T’s System III Unix to the IBM PC‑XT that keeps the System III system calls while adding PC‑friendly tools (like the INed editor and Connect) and performance tweaks such as contiguous file loading and optional 8087 floating‑point support.
  2. Because the 8088 lacks memory protection, PC/IX is sold as a single concurrent‑user, multitasking system that needs a 10 MB hard disk and ships on 19 floppies; IBM will support the product while ISC provides polished documentation and a device‑driver guide to enable extensions.
  3. ISC expects a fast growth of third‑party and ISC applications (languages like COBOL and FORTRAN, INmail/INnet/FTP, word processing and databases) and believes IBM’s marketing and support will help drive adoption and encourage vendors to port their software to PC/IX.
Get a weekly roundup of the best Substack posts, by hacker news affinity:

The Archive

Justin E. H. Smith's Hinternet • 708 implied HN points • 14 Aug 25
📚 Literature Documentation
  1. Words can disappear for different reasons, like being banned or forgotten, and it can really change how we express ourselves and perceive the world.
  2. The act of sharing and speaking these lost words can help bring them back to life, making them part of everyday conversations again.
  3. Even if we can't save every word, every time someone uses a forgotten word, it's a small victory in keeping our language alive.

6 Must Have Software Engineering Templates

High Growth Engineer • 2002 implied HN points • 02 Feb 25
🕹 Technology Documentation
  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.

Making Science More Reproducible

Briefly Bio • 158 implied HN points • 18 Jul 24
🔬 Science Documentation
  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.

Anatomy of Oscillation

Software Design: Tidy First? • 1060 implied HN points • 10 Feb 25
🕹 Technology Documentation
  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.

Good Docs Describe, Bad Docs Prescribe

Rethinking Software • 299 implied HN points • 25 Jul 25
🕹 Technology Documentation
  1. Good documentation should describe the current state of the software, not what it might be in the future. This keeps it relevant and useful.
  2. Documents like ADRs and RFCs can become roadblocks if they're written too early. They can hold teams back instead of helping them move forward.
  3. The best documentation comes from the code itself, such as generated docs or inline comments. This helps ensure that the documentation matches the actual software.

Self-documenting Makefiles

Blog System/5 • 827 implied HN points • 10 Jan 25
🕹 Technology Documentation
  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.

Making API Documentation Dynamic

The API Changelog • 1 implied HN point • 06 Mar 26
🕹 Technology Documentation
  1. High-quality documentation shapes how developers judge an API, so make docs easy to use and remove anything that creates friction.
  2. MDX lets you embed components and run JavaScript inside docs so users see personalized data and can try requests, which speeds onboarding and lowers Time to First Call (TTFC).
  3. MDX adds power but also build steps and maintenance overhead, so weigh that complexity against a simple Markdown README when resources are limited.

How I Use AI

Jobs For AI • 26 HN points • 07 Jul 24
🕹 Technology Documentation
  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

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

well, actually • 196 implied HN points • 22 Feb 23
🎭️ Culture 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.

Literate Testing

Rethinking Software • 99 implied HN points • 14 Jun 25
🕹 Technology 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.

Building developer community and trust in today’s AI-first world

Dev Interrupted • 14 implied HN points • 11 Dec 25
🕹 Technology Documentation
  1. AI assistants are becoming a primary discovery channel for developers, so content must work well for both humans and machines.
  2. Treat documentation as a product: structure docs in machine-readable formats and make them authoritative so AI gives accurate, trusted answers.
  3. Keep humans at the center. Use AI to scale support and mixed-mode experiences, and update metrics to measure AI visibility and developer trust.

Bad Software Advice: Three Interesting Links #6

Bad Software Advice • 164 implied HN points • 20 Jan 25
🕹 Technology 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.

The future of APIs is promising and bleak

microapis.io • 58 implied HN points • 11 Jan 24
🕹 Technology Documentation
  1. The way APIs are built today makes them pervasive, but we still struggle to work effectively with them.
  2. Improving API development involves focusing on accountability and security.
  3. For better APIs, focus on clear specifications, formal documentation, and rigorous security testing.

"Organic Markdown" Intro

Rethinking Software • 199 implied HN points • 21 Aug 24
🕹 Technology Documentation
  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.

How Nigeria Elected a Criminal as Its President: Part I

Aaron Greenspan • 369 implied HN points • 08 Dec 23
🌍 World Politics 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.

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 Documentation
  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 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.

How to do developer marketing that doesn’t suck

Developer GTM – by Calyx Consulting • 59 implied HN points • 24 Aug 23
💼 Business Documentation
  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 Documentation
  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 Documentation
  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.

Ensemble Weather Forecast API

Open-Meteo • 351 implied HN points • 05 Jun 23
🕹 Technology 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 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.

My Markdown personal management system

normality’s Substack • 3 HN points • 25 Jul 24
🕹 Technology 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.

The Joy of Literate Programming

Rethinking Software • 99 implied HN points • 02 Sep 24
🕹 Technology Documentation
  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!

Creating a Security Posture Report for a Specific Azure Subscription

Rod’s Blog • 19 implied HN points • 13 Feb 24
🕹 Technology 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.

Tip: Catch up on Microsoft Security Copilot Over a Weekend

Rod’s Blog • 39 implied HN points • 11 Oct 23
🕹 Technology Documentation
  1. You can generate a PDF for the entire Security Copilot documentation. The existing Docs produce a PDF of about 95 pages.
  2. The Security Copilot Docs are constantly being updated, so remember to produce new versions of the PDF from time-to-time.
  3. You can send documents to your Kindle library on Kindle devices and app using the 'Send to Kindle' feature, with end-to-end encryption for protection.

Digging into GitHub Actions

One Thing at a Time • 39 implied HN points • 24 Mar 23
🕹 Technology Documentation
  1. Automate project management and collaboration tasks with GitHub Actions to improve efficiency and code quality.
  2. Integrate GitHub Actions with Project Boards to streamline project management and task tracking.
  3. Collaborate with external teams and services using GitHub Actions to facilitate seamless communication and integration.

The loneliness of the long distance runbook

Wednesday Wisdom • 56 implied HN points • 11 Dec 24
🕹 Technology Documentation
  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.