Skip to content

Method of Logging Site Updates

Context and Problem Statement

Would it be good to record somewhere what considerations were made and what decisions were taken for creating the site? While pondering how to explain the creation process in comments after announcing the portfolio site creation news on LinkedIn, I thought that logging the main decisions could be useful for similar situations in the future.

Decision Drivers

  • I hope it would be easy to log consistently. In other words, I'd like the log management to be simple.
  • I'd like it to be easy to view what decisions were made.

Considered Options

  • Manage with GitHub commits (maintain current situation)
  • Manage with GitHub issues and PRs
  • Create ADR documents

Decision Outcome

Chosen option: "Create ADR documents", because

  • By publishing ADR documents on the site, I don't need to show the hidden GitHub repo behind it.
  • Gaining more experience in writing ADR documents is judged to be helpful for future development projects.

Pros and Cons of the Options

Manage with GitHub commits (maintain current situation)

  • Good, because no additional effort is needed to maintain the current system.
  • Neutral, because going through commit logs might not be easy for others to understand.
  • Bad, because commits don't contain considerations and records of options I didn't choose.

Manage with GitHub issues and PRs

  • Good, because just looking at issues and PRs later can show what topics have been covered, serving as sufficient logging.
  • Good, because it utilizes a system already implemented in GitHub, so there's no need to build a new management method.
  • Neutral, because developers can understand the site management method to some extent just by looking at the structure of issues and PRs.
  • Bad, because some effort is required to structure the management method so that PRs can serve as the standard for site updates.

Create ADR documents

  • Good, because whenever a major decision is made about the project, information can be organized at the desired level.
  • Neutral, because it's possible to write them somewhere regardless of whether they're public or not. And it's not difficult for the general public to understand.
  • Bad, because a new management system needs to be set up, which requires effort.