3 posts tagged with "documentation"

Overview​

I had the pleasure of presenting my thoughts about documentation as code, this time at DDD Melbourne.

The main point of this talk is to focus your documentation on filling the gaps between the obvious, how can you make your codebases easily discoverable and enable new team members to join your project and quickly get up to speed and provide valuable contributions in the shortest possible time.

Below is a quick visual outline of my presentation.

• Overview - README.MD Markdown files to help developers understand what they're looking at.
• Get Started - README.MD Markdown file with more information to help developers get started, install dependencies, etc.
• Old Decisions - Architecture Decision Records to understand what decisions have been made in the past, and why.
• New Decisions - Architecture Principles to help guide future decisions.
• Architecture - Diagrams to help developers understand the architecture of the system.
• Sharing - Use mkdocs to to share documentation with the team.
• Scaling - Ways to share and scale documentation as the team grows beyond a few repositories.

Recently, I’ve been working on a few internal projects that required creating and hosting documentation for our team.

However, one challenge consistently got in the way of me being able to quickly share the information: finding an uncomplicated yet secure way to host this valuable content.

Using a static content generator like mkdocs was my preferred approach, but I really wanted to avoid having to run it in a docker container or behind a web server in order to add authentication to the mix.

As it turns out, Azure Static Web Apps paired with MkDocs and Azure AD is a relatively simple solution to this problem. The documentation alludes to the fact you can do all of this, but it took a few hours of stuffing around to get it "just right". Hopefully this can save you the hassle.

Onboarding new team members can be a costly aspect of building and maintaining software, and this gets harder the bigger your organisation gets.

It's well known how much we cringe at the thought of having to write documentation, but thinking about it differently, and adopting a documentation-as-code approach we can remove the friction of this process.

In my talk, "Documentation for Developers", I share some stories and practices you can use to help make your software easier to understand for new developers joining the team. I also share some tools and techniques for capturing the architecture and design of your software.

Whether you're a one-person team hoping to scale up, or an enterprise with hundreds of repos, this talk will have some useful tips.