Skip to main content

2 posts tagged with "documentation"

View All Tags

· 6 min read
Shaw Innes

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.

· 4 min read
Shaw Innes

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.