Guidelines

To build this blog I decided to use the following guidelines:

  • Try to follow best practices for documentation, development and deployment

  • Document the reasoning behind decisions

  • Document the process of creating the blog

  • Focus on the content and the design

  • Use state-of-the-art tools and technologies

  • Start with the simplest solution and improve it over time

The following chapters describe how I try to follow these guidelines. == Processes

This section describes the processes I use to create and maintain this blog.

Development Process

The diagram below describes my current development process:

Diagram

Architecture

This chapter describes the architecture of my blog. The term is used in a very broad sense. Things that are considered architecture are:

  • Information Architecture

  • UI/UX Design

  • Navigation

  • Responsiveness

  • Technical Infrastructure

  • SEO

The following chapters describe each of these aspects in detail.

Navigation

I try to design the navigation as simple and intuitive as possible. It should eventually be possible to see the content of the blog visualized as a graph. The graph should be queryable and navigable. For now it is just a list of links. A simplified version of the navigation is shown below:

Diagram

It is simplified because lower nodes might have links back to higher nodes which are not shown here. === Development Guideline

This document describes how I develop a new feature for my blog. The development process is described in the following steps:

Diagram

Commits

Commit messages should follow the specification for Conventional Commits. Thus, commits should have the following structure

<<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>

where:

  • type must be one of:

    • task,

    • system,

    • build,

    • chore,

    • ci,

    • docs,

    • feat,

    • fix,

    • perf,

    • refactor,

    • revert,

    • style,

    • test

    • dev-config

    • deps

  • scope is optional but must be one of:

    • tbd

Examples can be found here

Build

tbd == Tasks

In this chapter all tasks to be done are described. Each task must describe a clear expected result. Task with open questions are described in tasks with open questions.

All tasks should contain at least the following information:

  1. Goal - why is this task necessary?

  2. Requirements - what is the expected result and its constraints?

  3. Hints - which information we know already can be used to implement this task?

  4. Result - must be verifiable

Thus, the following can be used as a template for a task:

  • Goal

    • <goal and the reason why it makes sense to achieve it>

  • Requirements

    • <list of requirements and their constrains>

  • Hints

    • <hints which can be used to implement the task>

  • Result

    • <description of the expected result>

Tasks In Progress

  1. Implement root page according to mockup

    • Goal

      • Implement root page according to mockup in Figma

    • Requirements

      • Root page looks like mockup

    • Hints

      • Reuse/Extend existing components for Material Design 3

Backlog

Implement navigation functionality

  1. Navigation Functionality

    • Goal

      • Implement basic navigation functionality for the blog-like web app, allowing users to easily navigate through the site and access different sections as described in the provided sitemap. This will enhance user experience and help them find relevant content efficiently.

    • Requirements

      • Ensure the navigation bar or menu is easily accessible and visible on all pages of the website.

      • Ensure the navigation bar or menu is responsive and adapts well to different screen sizes, such as mobile, tablet, and desktop.

      • Create a navigation bar or menu containing links to each section of the website as described in the sitemap depicted below.

      • The navigation functionality should follow web accessibility guidelines to support users with disabilities. Hints

      • Consider using popular front-end libraries and frameworks, such as Bootstrap or Tailwind CSS, to create a responsive and accessible navigation bar.

      • You may use the <nav> HTML element to create a semantic and accessible navigation bar.

      • Utilize CSS media queries to adapt the navigation bar or menu to different screen sizes.

    • Result

      • The implemented basic navigation functionality will allow users to easily access and navigate between different sections of the website, as described in the sitemap. The navigation bar or menu will be responsive and accessible, ensuring a smooth user experience across various devices and for users with disabilities.

Diagram

Tasks With Open Questions

Completed Tasks

Tools

tdb