<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Documentation on Derald's Workbench</title><link>https://derald.com/tags/documentation/</link><description>Recent content in Documentation on Derald's Workbench</description><generator>Hugo -- gohugo.io</generator><language>en-us</language><copyright>© 2026 Derald R. Grimwood Jr.</copyright><lastBuildDate>Fri, 10 Jul 2026 08:00:00 -0700</lastBuildDate><atom:link href="https://derald.com/tags/documentation/index.xml" rel="self" type="application/rss+xml"/><item><title>A System Should Explain Itself</title><link>https://derald.com/posts/readable-systems/</link><pubDate>Fri, 10 Jul 2026 08:00:00 -0700</pubDate><guid>https://derald.com/posts/readable-systems/</guid><description>&lt;p&gt;Documentation is often treated as a report written after the real work is finished. That arrangement almost guarantees that the report will fall behind.&lt;/p&gt;
&lt;p&gt;A system should explain itself while it is being built.&lt;/p&gt;
&lt;p&gt;That does not mean filling the source with noise or generating pages nobody reads. It means designing visible contracts:&lt;/p&gt;</description><content>&lt;p&gt;Documentation is often treated as a report written after the real work is finished. That arrangement almost guarantees that the report will fall behind.&lt;/p&gt;
&lt;p&gt;A system should explain itself while it is being built.&lt;/p&gt;
&lt;p&gt;That does not mean filling the source with noise or generating pages nobody reads. It means designing visible contracts:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;commands with clear names&lt;/li&gt;
&lt;li&gt;help derived from governed catalogs&lt;/li&gt;
&lt;li&gt;runtime checks that prove behavior&lt;/li&gt;
&lt;li&gt;examples that can be executed again&lt;/li&gt;
&lt;li&gt;architecture boundaries that are stated and tested&lt;/li&gt;
&lt;li&gt;documentation linked to implementation evidence&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="teaching-exposes-weak-design"&gt;Teaching exposes weak design&lt;/h2&gt;
&lt;p&gt;A programmer can become accustomed to unexplained conventions. A student cannot. When a system is difficult to teach, the difficulty may be in the subject—but it may also be in the design.&lt;/p&gt;
&lt;p&gt;Teaching asks the questions that maintenance eventually asks:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;What is this object responsible for?&lt;/li&gt;
&lt;li&gt;Where does this state live?&lt;/li&gt;
&lt;li&gt;What happens before and after the command?&lt;/li&gt;
&lt;li&gt;Which behavior is guaranteed?&lt;/li&gt;
&lt;li&gt;How can I prove it?&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Software that can answer those questions is easier to teach, but it is also easier to maintain.&lt;/p&gt;
&lt;h2 id="evidence-is-better-than-confidence"&gt;Evidence is better than confidence&lt;/h2&gt;
&lt;p&gt;A large project accumulates confident statements. Some are true, some were true, and some describe an intention that never became implementation.&lt;/p&gt;
&lt;p&gt;Runtime evidence, repeatable tests, generated catalogs, and reviewed documentation help separate those categories.&lt;/p&gt;
&lt;p&gt;The goal is not paperwork. The goal is a system whose claims can be checked.&lt;/p&gt;</content></item></channel></rss>