Testified Documentation

Posted on 29 September 2024 in Articles • Tagged with programming, python, documentation, tests, specification, BDD, collaboration, cucumber • 5 min read

It's hard to sell a software product - whether it's a library, a program, or generally speaking, a system - if it doesn't come with a top-notch manual. And keeping such manual up-to-date is not easy too. Gojko Adzic's ideas of Living Documentation to the rescue, but unfortunately they are still far from being widely adopted.

In this post I propose a different way of making Living Documentation - by testifying its contents. Dive in to find out how!

Testified documentation diagram

Continue reading

The Mythical Man-Months - thoughts

Posted on 19 March 2024 in Books • Tagged with book, review, software development, programming, management • 22 min read

"Then Mythical Man-Months" by Frederic Broogks book cover

As the year 2023 was coming to an end, I finally had some time to recap "The Mythical Man-Month: Essays on Software Engineering" by Fred Brooks. The book talks about software development fallacies from software engineering and project management perspectives. However this is not "yet another book". It was first published in 1975, nearly fifty years ago! So much changed since 1975, and yet, so little! It's unbelievable that today we are still struggling with the problems that haunted us in the age of mainframes.

You smile a lot as you read the book. Programming with punch cards? A big fat machine with only 2 MB of RAM? Software documented on paper? Sure, things were different back then. But there are so many similarities! Instead of reviewing the book, I'd prefer to study these similarities, draw parallels, and find out whether things have changed for the better.


Continue reading

The DevOps Handbook - review

Posted on 11 August 2023 in Books • Tagged with book, review, devops, software development, programming • 3 min read

"DevOps Handbook cover"

DevOps Handbook is a fantastic guide for IT organizations, that describes the ways of improving the technology value stream - the process required to convert a business hypothesis into a technology-enabled service that delivers value to the customer.


Continue reading

The curious case of denied repository access in Github Actions workflow

Posted on 01 June 2023 in Articles • Tagged with programming, blog, pelican, git, github, actions, ci/cd, access denied • 4 min read

Intro image for the article

While configuring a continuous delivery pipeline for this blog, I encountered unexpected permission denials from GitHub. Was there something wrong with the setup?


Continue reading

Clean Architecture - book review

Posted on 18 May 2023 in Books • Tagged with book, review, programming, architecture, clean code, clean architecture • 6 min read

"Clean Architecture" book cover

Clean Architecture is the "Art of War" of the software industry. It was written by a professional who has been through many tough battles, both wins, and losses. Uncle Bob talks about timeless topics of software development that are just as applicable today as they were fifty years ago.


Continue reading

Specification by example - book review

Posted on 21 February 2023 in Books • Tagged with book, review, programming, specification, requirements, BDD, collaboration • 4 min read

"Specification by Example" by Gojko Adzic book cover.

Doing things right doesn't matter unless you do the right thing. "Specification by Example" by Gojko Adzic is about delivering the right software. Adzic has interviewed many successful teams and discovered that their ways of software development are quite similar. These ways or processes are based on a close collaboration between all the parties, including business representatives. It begins by understanding the business goals. It continues with creating a specification and utilizing it for software development and verification. It is finalized by providing living documentation which reflects the current software state and behaviour.

"Specification by Example" helped me to understand how to do behaviour-driven development (BDD). It is an excellent reading for a software craftsman.


Continue reading

Hexagonal architecture and Python - Part III: Persistence, Transactions, Exceptions and The Final Assembly

Posted on 31 December 2022 in Articles • Tagged with architecture, DDD, dependency injection, Django, hexagonal architecture, programming, python • 10 min read

Python logo in a hexagon with Roman III literal

Welcome to the third part of the article series, which cover principles of Hexagonal architecture, Dependency Injection, Domain-Driven Design and applies these all to Python and Django application design.


Continue reading

Refactoring - book review

Posted on 15 October 2022 in Books • Tagged with book, review, programming, refactoring, Martin Fowler, Kent Beck • 4 min read

"Refactoring" book front cover

Refactoring is a book by Martin Fowler about what a fellow developer might describe as "a process of improving the code quality."

I highly recommend this book to software professionals who want to improve and formalise their refactoring skills.


Continue reading

Hexagonal architecture and Python - Part II: Domain, Application Services, Ports and Adapters

Posted on 18 September 2022 in Articles • Tagged with architecture, DDD, dependency injection, hexagonal architecture, programming, python • 10 min read

Python logo in a hexagon with Roman II literal

Welcome to the second part of the article series, which cover principles of Hexagonal architecture, Dependency Injection, Domain-Driven Design and applies these all to Python and Django application design.


Continue reading

Good practices: Avoiding the use of test inputs in assertions

Posted on 10 November 2021 in Articles • Tagged with good practices, programming, python, testing, unit tests • 2 min read

Figure of eight know / https://freesvg.org/figure-of-eight-knot-vector-illustration / License: Public Domain

It might be very convenient to use the same fixtures in test setup and assertions. This practice though is not as good as it looks like at first glance.


Continue reading