Inspired by Peter Turchi's "Maps of the Imagination: The Writer as Cartographer," we explore the convergence of cartography and technical writing in software documentation. We'll delve into how maps, as narratives that guide and inform, parallel the goals of effective documentation—telling the story of a codebase and providing clear navigation, We'll uncover insights on crafting documentation that serves as a compass for developers, marrying the art of storytelling with the precision of technical detail to create a more navigable and understandable software landscape.

There are many tools out there for ""writing"" your graphs and design diagrams, one the best ones by far is Mermaid.

It is supported out-of-the box by many tools including Notion and Github. It makes it very easy to use without any extra steps.

Using Mermaid, you can have a readable, maintainable text that represents your visuals. You can think of it as visuals as code.

Being able to use the same tools you use for coding for creating your visuals in the documentation is amazing, and is a great addition to already great Markdown language.

In a world of dependencies and online package management, documentation tools are designed and optimised around the question "how do I use your library?".

But for companies that build systems to do something, and not libraries, there is another critical question "how does the system work? how can I change it?"

Library-based documentation is inline with the code and under the same version control system.

All too often architectural documentation is outside the code and poorly kept in sync.

This talk will look at another way of thinking about documenting systems a way that keeps architectural docs in the github repo and which plays nice with ExDoc.

Gordon Guthrie has been an Erlang programmer since 2002 and an Elixir one for quite a bit less.

This presentation explores the innovative use of .process.md files to customize and direct AI coding assistants. We'll delve into how these markdown-based instruction sets act as "playbooks," enabling developers to codify specific workflows, enforce best practices, and teach the AI nuanced, context-aware behaviors for various development tasks.

Discover how .process.md files transform AI assistants from general-purpose tools into highly specialized and effective pair programming partners, enhancing productivity and code quality through structured, repeatable processes.