Documentation on Brandon Pugh's Blog

Zeal offline documentation browser

Wed, 18 Oct 2023 00:00:00 +0000

Today I learned about a cool project called Zeal that let’s download and browse the documentation for a bunch of projects. I’ve always liked the idea being able to continue working even without internet.

Thank you for keeping RSS alive. You're awesome.

Reply by email

The C4 model for visualizing software architecture

Wed, 02 Aug 2023 00:00:00 +0000

Today I learned about the C4 model for visualizing software architecture. It looks like a nice framework for thinking hierarchically about the architecture of a system and how best to go about conveying it visually.

Thank you for keeping RSS alive. You're awesome.

Reply by email

Sequence Diagrams

Thu, 20 Jul 2023 00:00:00 +0000

I learned how to correctly read sequence diagrams. I came across a recent post that suggests “Sequence diagrams are the only good thing UML brought to software development”. I’d never thought they were that useful but it turns out that was because I’d been misreading them.

There’s probably been a few instances over the years where I’ve made a flowchart where a sequence diagram would have been better. For example, I tend to add a high-level overview of how a request moves through our application especially since Mermaid.js makes it really easy to add to markdown documentation (Github and Azure DevOps will both render them).

Here’s a quick example of a typical vertical slice architecture we would use at Headspring. Adding this code block to a markdown file will render a sequence diagram using Mermaid:

  sequenceDiagram
    UI->>api: http request
    participant api as API controller
    Note over UI,api: This gets bound to a viewModel <br/>(*[Query|Command].cs)
    participant mediatr as Mediatr handler
    api->>mediatr: Mediatr request
    mediatr->>DB: Entity framework query
    DB-->>mediatr: DB records
    Note over mediatr: Business logic/validation
    mediatr-->>api: Response data
    Note over api,mediatr: viewModel (*[Response|Command].cs)
    api-->>UI: http response

Rendered on Github:

Thank you for keeping RSS alive. You're awesome.

Reply by email