GitLab and PostHog Handbooks

Mike's Notes

I have been convinced of the wisdom of having a public handbook.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

13/09/2025

GitLab and PostHog Handbooks

By: Mike Peters
On a Sandy Beach: 08/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

I recently came across PostHog and discovered they had an open handbook on how they work. In turn, they were inspired by the GitLab handbook. I  have a lot of similar material looking for a home. Being open and transparent is a good plan. I will shamelessly copy the layout and format of these handbooks and create one for Ajabbi using my own content. I also liked the very open editorial policy of Smashing Magazine. Remote also has a handbook.

I just discovered GitHub as an open handbook.

Creative Commons has a public policy archive.

Antono has an open handbook.

Views of software documentation

Mike's Notes

These great software engineering newsletters are found on SubStack.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Views of software documentation

By: Mike Peters
On a Sandy Beach: 07/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Newsletters

Recent posts

Diataxis Framework

Laws of software

Mike's Notes

Note

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Laws of software

By: 
Wikipedia: 2024

"In software engineering, the laws of software evolution refer to a series of laws that Lehman and Belady formulated starting in 1974 with respect to software evolution.The laws describe a balance between forces driving new developments on one hand, and forces that slow down progress on the other hand. Over the past decades the laws have been revised and extended several times. ...

All told, eight laws were formulated:

  1. (1974) "Continuing Change" — an E-type system must be continually adapted or it becomes progressively less satisfactory.
  2. (1974) "Increasing Complexity" — as an E-type system evolves, its complexity increases unless work is done to maintain or reduce it.
  3. (1974) "Self Regulation" — E-type system evolution processes are self-regulating with the distribution of product and process measures close to normal.
  4. (1978) "Conservation of Organisational Stability (invariant work rate)" — the average effective global activity rate in an evolving E-type system is invariant over the product's lifetime.
  5. (1978) "Conservation of Familiarity" — as an E-type system evolves, all associated with it, developers, sales personnel and users, for example, must maintain mastery of its content and behaviour to achieve satisfactory evolution. Excessive growth diminishes that mastery. Hence the average incremental growth remains invariant as the system evolves.
  6. (1991) "Continuing Growth" — the functional content of an E-type system must be continually increased to maintain user satisfaction over its lifetime.
  7. (1996) "Declining Quality" — the quality of an E-type system will appear to be declining unless it is rigorously maintained and adapted to operational environment changes.
  8. (1996) "Feedback System" (first stated 1974, formalised as law 1996) — E-type evolution processes constitute multi-level, multi-loop, multi-agent feedback systems and must be treated as such to achieve significant improvement over any reasonable base. " - Wikipedia

Design System Documentation

Mike's Notes

Developers and designers need public documentation for the Pipi 9 Design System.

I started by looking at great examples of successful documentation.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Design System Documentation

By: Mike Peters
On a Sandy Beach: 05/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Some examples:

-  Source - Smashing Magazine

The Pipi 9 Design System is database-driven. Templates must be able to use structured data to generate a nested directory structure and web pages.

As a single source of truth, changes in the design system should change both the documentation and CMS production automatically.

API

Later, it also needs to drive an open API to connect to Figma and other tools.

Audiences

There are at least two audiences who will require different sets of documentation.

  • Developers
  • Designers

  • Everyone else

Structure

Taking the Material Design documentation as a pattern, how is the documentation organised. 

  • Home page introduction
  • List of components.
  • A page for each component
  • List of design tokens
  • A page for each token
  • Layout

  • etc

Template examples





Inspired by Nathan Curtis

Documentation sections or tabs

  • Introduction.
  • Examples—the venerable “goods” they are most after—front and centre.
  • Design guidance expands on examples yet drifts into storytelling of uncertain length.
  • Accessibility
  • Code reference, predictably structured and dependably authored. If engineers are the priority and Props paramount, elevate that reference table into a dominant position.

Chinese -Japanese - Korean

Mike's Notes

I'm starting to gather notes on how to support asian writing systems.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

18/04/2025

Article

By: Mike Peters
On a Sandy Beach: 05/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

"In internationalisation, CJK characters are a collective term for graphemes used in the Chinese, Japanese, and Korean writing systems, which each include Chinese characters. The term CJKV also includes Vietnamese, which was also historically written with Chinese characters. ..." - Wikipedia

Chinese

Japanese


Korean


Design System database

Mike's Notes

More i18n adventures.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Article

By: Mike Peters
On a Sandy Beach: 03/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

In early 2023, I built a database that could store multiple design systems. The goal was to give Pipi 9 users the ability to change any application's front-end web user interface (UI).

Last week, I finally got around to using it and making some changes to prepare it for production.

I imported the CSS style sheets used by the Pipi 4-generated " bush wiki" website to generate a design system for public web pages and documentation. It looks similar to Wikipedia.

Then, I created a design system for work interfaces based on Metro UI. It resembles Microsoft Windows and Microsoft Office.

The database stores the CSS, UI Components and Design Tokens, making it easy to make system-wide changes.

I used the guidance provided by Nathan Curtis on how to standardise the naming of design tokens. That means

"To be sufficiently descriptive, a tokenized language that incorporates both taxonomy and typology needs many levels. Enough levels, as it turns out, to organize them into groups:

  • Base levels as a token’s backbone that combine category (for example, color), concept (action) and property (size).
  • Modifier levels to refer to one or more of variant (primary), state (hover), scale (100), and mode (on-dark).
  • Object levels to refer to a component (button), element within a component (left-icon), or component group (forms).
  • Namespace levels combining any (or all, in extreme cases!) of system (esds), theme (ocean or subbrand), or domain (retail)."
- Nathan Curtis

Examples of Ajabbi Design System - design tokens

Ribbon Menu

  • ajabb-ui-ribbon
  • ajabb-ui-ribbon-tab-holder
  • ajabb-ui-ribbon-tab-content

<nav data-role="ajabb-ui-ribbon">
    <ul class="ajabb-ui-ribbon-tab-holder">
        <li class="static"><a href="#">Static</a></li>
        <li><a href="#section-one">One</a></li>
        <li><a href="#section-two">Two</a></li>
        <li><a href="#section-three">Three</a></li>
    </ul>
 
    <div class="ajabb-ui-ribbon-tab-content">
        <div class="ajabb-ui-ribbon-tab-section" id="section-one">
            <p class="p-4">Section one</p>
        </div>
        <div class="ajabb-ui-ribbon-tab-section" id="section-two">
            <p class="p-4">Section two</p>
        </div>
        <div class="ajabb-ui-ribbon-tab-section" id="section-three">
            <p class="p-4">Section three</p>
        </div>
    </div>
</nav>

Design System Documentation

Using the Design System database as a source, the Pipi 9 Render Engine should be able to batch render a complete HTML documentation set for the Design System, which can then be made publicly available and shared on GitHub.

CSS

Any style sheets (CSS) will be editable via web forms. Again, the style sheets can then be batch-rendered.

CMS

The content management system uses the design system to fully automate the production of every web page. This setup suits huge websites with hundreds of templates and thousands of pages, such as newspapers, dictionaries, universities, museums, and large, complex workplaces.

Building a Design System

Mike's Notes

Pipi 9 has been headless and is now getting a web front end. It has its own working Content Management System (CMS) but doesn't have a Design System. Here is a list of reference material.

Resources

  • Resource

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Building a Design System

By: Mike Peters
On a Sandy Beach: 03/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Design Systems

"A design system is a collection of reusable components and clear standards that can be assembled together to build any number of applications. Design systems aid in digital product design and development of products such as mobile applications or websites. They may contain but are not limited to, pattern/component libraries, design languages, style guides (font, color, spacing, placement), coded components, brand languages, and documentation.

It serves as a reference in combination with a design language that ensures the many different teams involved in designing and building a product create cohesive products that look and behave like each other.

Notable design systems include Lightning Design System (by Salesforce), Material Design (by Google), Carbon Design System (by IBM), and Fluent Design System (by Microsoft). ..." From Wikipedia 

Examples of Design Systems

Material design by Google

‍Apple Design Resources
Audi User Interface Guidelines
Base: Uber's design system
Microsoft Fluent Design System
IBM carbon design system
UK Gov Design System
Spectrum: Adobe Design System
Nord Health Design System
GitLab Design System
More here

Useful Resources

Components

A component is a single, reusable chunk of a user interface.

Examples of components from UK Govt Design System

  • Accordion
  • Backlink
  • Breadcrumbs
  • Button
  • Character count
  • Checkboxes
  • Cookie banner
  • Date input
  • Details
  • Error message
  • Error summary
  • Exit this page
  • Fieldset
  • File upload
  • Footer
  • Header
  • Inset text
  • Notification banner
  • Pagination
  • Panel
  • Phase banner
  • Radios
  • Select
  • Skip link
  • Summary list
  • Table
  • Tabs
  • Tag
  • Task list
  • Text input
  • Textarea
  • Warning text

Component Resources

Design Tokens

"Design tokens are the building blocks of all UI elements. The same tokens are used in designs, tools, and code. Design tokens represent the small, repeated design decisions that make up a design system's visual style. ... Tokens replace static values, such as hex codes for color, with self-explanatory names. ..." (From Material Design System)

Nathan Curtis has worked on many projects and has written many articles about design tokens.

Resources from The Component Gallery

Websites

  • styleguides.ui is a collection of website style guide articles, books, podcasts, talks, tools, and examples. 

Books

w3tech Web Technology Surveys

Mike's Notes

Note

Resources

  • Resource

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

w3tech Web Technology Surveys

By: Mike Peters
On a Sandy Beach: 01/06/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

I came across this helpful website that surveys the relative use of different web technologies.

https://w3techs.com

The regularly updated reports include the following;

There is also a nifty tool to examine the technology used by a particular domain

DB-Engines

Mike's Notes

A helpful reference website.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

DB-Engines

By: 
DBEngines: 29/05/2024

"DB-Engines is an initiative to collect and present information on database management systems (DBMS). In addition to established relational DBMS, systems and concepts of the growing NoSQL area are emphasized.

The DB-Engines Ranking is a list of DBMS ranked by their current popularity. The list is updated monthly.

The most important properties of numerous systems are shown in the overview of database management systems. You can examine the properties for each system, and you can compare them side by side.

In the database encyclopedia terms and concepts on this topic are explained.

DB-Engines has been created and is maintained by solid IT." - from DBEngines.

Ranking

The DB-Engines Ranking ranks database management systems according to their popularity. The ranking is updated monthly.

Reports

Each database gets a detailed single-page report

Translation API

Mike's Notes

I have been using Google Translate to translate text strings from English to other languages. It is fast, reliable, and easy to use.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

17/05/2025

Article

By: Mike Peters
On a Sandy Beach: 23/05/2024

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

There are also translation APIs available.

  • Google Translate API
  • IBM Watson Language Translator
  • Microsoft Text Translation
  • Yandex
Google Research is working on translating 1000 + languages