Guidelines for Writing Examples and Demos

Examples and demos are an essential part of the documentation. They help readers understand not only what an API does, but also how to use it effectively in real-world situations.

Whenever you explain an API, feature, or workflow, include practical examples from the perspective of a library user. Well-written examples reduce the learning curve, communicate best practices, and make the documentation more engaging.

Good examples should be:

  • concise,

  • realistic,

  • easy to understand,

  • focused on a single concept,

  • immediately useful to the reader.

Avoid overly artificial examples that only demonstrate syntax without meaningful context.

Code Style

All example code must follow the Erbsland code style.

Whenever possible, format code automatically using the pre_commit utility to ensure a consistent appearance across the documentation.

In General

  • Keep formatting clean and readable.

  • Prefer modern C++20 style.

  • Avoid unnecessary boilerplate.

  • Keep examples compact without hiding important details.

For Demos

  • Add an API documentation block (///) that describes the API, concept, or class being demonstrated.

  • Everything before the first /// line gets cut-off in the documentation. Constants, functions, declarations that only add noise can be put in front to hide them.

  • Everything after the namespace demo { ... } block gets cut-off in the documentation.

  • This documentation is reused in the generated documentation and should be useful when read independently from the surrounding text.

  • The text in demo documentation blocks often intentionally duplicates information that may already be visible in the code. This redundancy improves search, embedding quality, and the discoverability of APIs through natural-language queries.

  • Prefer explaining the purpose and capabilities of the API over describing the individual demo steps.

  • The documentation block also serves as semantic context for documentation search and embedding-based knowledge retrieval.

  • Do not shorten the documentation block merely to match the size of the demo. A concise API description is usually more valuable than a minimal description of the example itself.

  • Add short comments (//), what is done in the next block of code,

  • to semantically link it with the following API use for embeddings to be bound to the code,

  • and as users reading the documentation may be unfamiliar with the API.

API Usage

Always write examples from the viewpoint of a library user. Always write read-world examples a user might find useful for their own code.

Readers should immediately understand how they would use the API in their own code. Avoid implementation-focused examples unless the topic explicitly requires them.

Guidelines:

  • Use the short namespace alias el instead of erbsland.

  • Collapse domain namespaces whenever possible:

    el::text::String  ->  el::String

  • Prefer concise and realistic examples.

    Instead of:

    auto text = erbsland::text::String{std::string_view{"Hello"}};

    Write:

    auto text = "Hello"_el;

  • Prefer the common string aliases and literals provided by the library:

    • String is an owning, read-only string for most purposes.

    • ""_el - everywhere for string literals

    • StringFormat - for formatting strings (or use el::io::print)

    • StringEditor - for examples that explicitly demonstrate local in-place editing or small construction tasks.

  • Avoid unnecessary usage of standard library string types in examples unless they are directly relevant to the topic.

Language and Themes in Example Code

  • Non-english natural language must only be used in data, values or input an example/demo processes. It is a good method to separate user-input from application logic.

  • Error messages, diagnostic output, and any output that explains the behavior of the example/demo must be English.

  • Only if you choose a theme and language manually, see Themes and Languages for Examples and Demos for a comprehensive list.

Unicode and Emojis

The library provides excellent Unicode support. Do not hesitate to use Unicode characters and emojis in example code when they improve readability or make examples more engaging.

Well-placed Unicode text often makes examples feel more realistic and memorable.