Concise Manuals for People and Machines

Andrey Akinshin

The process of programming is evolving. The skills required for programmers are also changing. There was a time when I measured my abilities by the number of tools, frameworks, and libraries I knew. The more I knew, the more valuable I seemed. That feeling is gone.

Now, engineering activities are shifting from writing code to describing tasks, validating results, and making corrections. The idea is becoming more important than the source code. Natural language prompts are slowly becoming the fifth-generation programming language.

Writing follows a similar pattern. At the beginning of the writing process, I come up with an idea and actively think, which is enjoyable. At the end, I have the finished product, which is also rewarding. But the middle part—editing, restructuring, formatting, checking references—is tedious. What was once fun has become routine. Experience transforms repetition into craft, and craft can be automated with modern technologies.

The focus of self-education is shifting from mastering specific tools to enhancing creativity and self-expression. Writing and editing skills—particularly in crafting manuals—are becoming increasingly important. It’s worth learning how to write manuals for machines that, in turn, would produce manuals for me.

After multiple experiments with LLM-based systems, I found that the ability to write clear, concise instructions is becoming a crucial skill. The challenge is achieving a good trade-off between token usage, response quality, and hallucination rate. This requires a systematic approach to documentation.

Writing for Both Audiences

When writing documentation today, we should keep both human and machine readers in mind. The same document should serve as:

  • A clear guide for human developers
  • An effective prompt for LLM-based tools
  • A reliable source for RAG systems

This dual-purpose writing requires careful attention to structure and clarity. Each piece of documentation becomes a potential instruction set for future automation.

The Art of Manual Writing

The methodology of manual writing often resembles a decision tree. It breaks down complex processes into series of small, atomic steps. The key principles include:

  1. Keep instructions concise (5-7 steps)
  2. Be explicit about important details
  3. Maintain consistent structure
  4. Focus on atomic, verifiable actions
  5. Include sufficient context

This approach works well because:

  • Humans can typically remember 7±2 items in short-term memory
  • LLMs experience similar limitations with context windows
  • Shorter instructions reduce the chance of steps being skipped
  • Clear structure improves both human comprehension and machine parsing

The Value of Documentation Skills

The ability to write good documentation is transforming from a nice-to-have skill into a crucial competency. When I document my thought process, preferences, and problem-solving approaches, I’m not just writing for other developers—I’m creating training material for AI assistants.

This documentation can serve multiple purposes:

  • Guide human developers through complex processes
  • Provide reliable prompts for LLM-based tools
  • Create consistent patterns for code generation
  • Establish clear validation criteria
  • Enable automated testing and verification

Future Implications

The challenge now becomes learning how to use this documentation effectively. By improving our ability to write clear, structured documentation, we enhance both human understanding and machine execution. This creates a positive feedback loop:

  • Better documentation leads to better prompts
  • Better prompts lead to better generated solutions
  • Better solutions inform better documentation

Programming in natural language could involve building engineering systems on top of agents and prompts, opening up intriguing new possibilities. The skill of writing clear, effective manuals becomes a multiplier for our existing capabilities.

What an interesting time to live.