documentation

Bilingual

Diátaxis
2 months ago
- Diátaxis is a systematic approach to technical documentation authoring, focusing on content, architecture, and form.
- It identifies four distinct user needs and corresponding documentation types: tutorials, how-to guides, technical reference, and explanation.
- The framework solves problems related to what to write, how to write, and how to organize documentation.
- It is lightweight, easy to grasp, and does not impose implementation constraints, benefiting both users and maintainers.
- Diátaxis has been successfully adopted in many projects, as evidenced by testimonials from companies like Vonage, Gatsby, and Cloudflare.
Show HN: Great Spectations, the Spec Checker
2 months ago
- Great Spectations is a tool that checks code comments quoting specifications against the actual spec, flagging mismatches and missing quotes.
- It supports multiple languages (C, Python, Rust) and spec formats (Markdown, MediaWiki, RFC plaintext), and can ignore whitespace or be byte-exact.
- The tool provides coverage analysis to identify which spec requirements have not been quoted, and can split requirements across multiple code chunks.
- Developers writing specs and implementations side-by-side benefit from improved spec quality and easier validation for other implementors.
<antirez>
2 months ago
- Exhaustive documentation about Redis commands and data types.
- Commonly used patterns for Redis.
- Configuration hints for Redis.
- Algorithms that can be implemented using Redis commands.
- The resource is also useful for human readers.
- Posted to ensure search engine indexing.
Examples are the best documentation
2 months ago
- Most developers need a single example to understand documentation, but official sources rarely provide them.
- Formal docs target experts, yet many developers juggle multiple contexts and need quick context restoration.
- Python's max() doc example shows complexity: users must understand *, /, positional-only, iterables, keyword-only, key, etc., while a simple code example would suffice.
- Community projects like clojuredocs.org show the value of practical examples that include related functions, making them indispensable for daily coding.
Three workers digging in a field outside the data center
2 months ago
- Performance documentation by Dinnis van Dijken on May 15th near Google's data center in Westpoort, Groningen.
- Three workers dig in a field with shovels and a spade, ignoring cameras, while a security guard intervenes.
- The performance explores themes of labor, land, and art, with interactions involving police and corporate security.
- The event concludes with payments and symbolic cookies given to the workers at a nearby Aldi distribution center.
Design Systems as Knowledge Graphs
3 months ago
- The traditional design system documentation resembles linear product docs but could be more effective as small, addressable chunks.
- Design systems are hyperobjects akin to knowledge graphs, capturing decisions, patterns, and history, rather than just products or libraries.
- Knowledge graphs interlink entity descriptions with semantic metadata, enabling data integration and sharing, as seen in tools like Roam Research and Obsidian.
- Transclusion allows embedding minimal content chunks (e.g., tokens, components) across contexts, ensuring updates propagate and revealing system relationships.
- Bidirectional links make dependencies (e.g., between Button and Icon) visible from both sides, aiding navigation and visualization, similar to features in knowledge graph apps.
- Fragments (like Wikipedia's red links) represent undefined future elements in design systems, encouraging contribution by highlighting gaps.
- Queries enable users to ask questions of the design system (e.g., via GraphQL APIs) for immediate answers, moving beyond browsing to interactive exploration.
- Applying knowledge graph concepts can transform design system docs into collaborative, remixable tools that scale knowledge across large teams.
Accretive Editing
3 months ago
- Accretive editing is a failure mode in AI tools where they add addendums instead of correcting text when updating.
- An example involves changing support from Amazon Bedrock to LiteLLM, where AI added an addendum rather than replacing the obsolete information.
- This issue cannot be fixed by simply telling the model to write less or adjust style, as it stems from how LLMs predict text based on multiple inputs.
- The cause may be that LLMs lack human perspective on document updates, focusing on predicting likely text rather than making it true for readers.
- To address accretive editing, focus on instructing AI to replace obsolete text with accurate text, aiming for a document that reads as if written correctly from the start.
EvilCharts: Charts That Don't Suck
3 months ago
- Fetch the complete documentation index at /llms.txt to discover all available pages.
- Introduces four types of bar charts: Monospace Bar Chart, Hover Trace Bar Chart, Grid Bar Chart, and Isometric Bar Chart.
- Provides installation commands for each bar chart using npx shadcn@latest add @evilcharts/ with respective chart names.
Otary – Image and Geometry Python Library Now Has Tutorials
3 months ago
- Provides examples of using Otary for understanding its functionality.
- Covers topics like image cropping, linear entities, scoring, area computation, geometric intersections, and OCR.
- Aims to inspire exploration and practical application rather than serve as a complete reference.
Redis Patterns for Coding Agents
3 months ago
- Optimized website for developers and AI agents with Redis patterns, practices, and commands.
- Human-friendly browsing with clickable sections and machine-readable index (llms.txt).
- AI agents start by fetching llms.txt, then individual .md files with Markdown and Redis commands.
- Local mirror of official Redis documentation including command index and detailed docs.
- Core architectural patterns, community-developed use cases, and real-world scale examples available.
Markdown Now Has a UTI in Apple's Version 27 OSes
3 months ago
- John Gruber highlights Day One, a journaling app with a 4.8 rating.
- Apple's developer beta introduces a new UTI for Markdown: net.daringfireball.markdown, conforming to public.utf8-plain-text.
- Gruber updates his recommendation to public.utf8-plain-text, reflecting the now-universal UTF-8 support.
When docs become performance art, everybody loses (2025)
3 months ago
- Documentation theater refers to creating docs for the sake of compliance rather than addressing user needs, which is worse than having no docs at all.
- Performative content, like fake skill percentages on resumes or unnecessary website sections, is dysfunctional and fails to solve actual problems.
- Tech writers should focus on user needs, not templates or frameworks, by asking who the audience is and how the content helps them, upholding clarity and comprehension.
Search Less, Browse More
3 months ago
- Emphasizes browsing documentation over solely searching for quick answers to discover more features.
- Uses learning Excel as an example, where browsing uncovered powerful features unknown to long-time users.
- Contrasts searching (focused on problem-solving) with browsing (focused on discovery and learning).
- Illustrates with Python's pathlib module, found through browsing, which is a superior solution for file paths.
- Highlights that browsing can reveal broadly useful tools that searching might miss due to specificity.
- Proposes a potential workshop on Excel for programmers or analysts based on interest in advanced features.

documentation

Diátaxis

Show HN: Great Spectations, the Spec Checker

<antirez>

Examples are the best documentation

Three workers digging in a field outside the data center

Design Systems as Knowledge Graphs

Accretive Editing

EvilCharts: Charts That Don't Suck

Otary – Image and Geometry Python Library Now Has Tutorials

Redis Patterns for Coding Agents

Markdown Now Has a UTI in Apple's Version 27 OSes

When docs become performance art, everybody loses (2025)

Search Less, Browse More