Contributing to AI Singapore's AI Practitioner Handbook

Contributors: Ryzal Kamis, Assistant Head (MLOps) & Kenny WJ Chua, Senior AI Engineer

This miscellaneous chapter covers two main aspects of contributing to the handbook-- workflow conventions for writing a new sections, and conventions for the content in each chapter.

Workflow conventions for a new section

This section covers the steps required to write a new section of the handbook. In summary, the 5 steps are as follows:

Create new issue
Fill in issue details
Open new feature branch with name chX-issueNum
Add issue to board (i.e., GitHub Projects); move to review section when completed
Submit pull request to main branch

1. Create a new issue

2. Fill in issue details

3. Open new feature branch with name `chX-issueNum`

E.g., branch ch1-issue5 denotes the feature branch for issue 5, which is a section within chapter 1

4. Add issue to board (i.e., GitHub Projects); move to review section when completed

5. Submit pull request to main branch

Before submitting the pull request, please ensure that all items in the definition of done are completed. Please build the site locally, and visually verify that your contributions are displayed as intended. You may build the site from the base directory of the repository using the the CLI command:

jupyter-book build .

For AISG contributors, please submit your pull requests at least three working days before sprint review.

After reviewing your issue, reviewers will provide suggestions for edits, if any.

Content Conventions

This section covers the conventions that were adhered to in writing this book and how they affect the appearance as well as standardisation efforts. Aside from ensuring that this book remains readable and accessible, such conventions would make the process of maintaining and reviewing contributions manageable. The conventions are covered across 4 different sections:

Structure
Content
Language
Formatting

To expedite the process for checking if your contributions adhere to the conventions, you may refer to the table below:

Summary Checklist:

No subdirectories are to be created within chapter directories.
Only Markdown files are to be used for generating content.
If a Jupyter Notebook is used, use Jupytext pairing function to export to MyST flavoured Markdown file. Commit and version both files.
Ensure headers are in sequential order.
No manual table of contents.
Citations and bibliographioes are populated in the centralised BibTeX file book/references.bib and referred to correctly.
For language, use Singaporean Standard English.

SECTION	CHECK
Structure	Check that your content is in the appropriate location/directory.
Content	Focus on long-standing content like principles, strategies, design patterns, or digestible concepts.
Content	Minimise references to tools.
Content	Limit to 500 words.
Language	Write in the form of a continuous prose.
Language	Use singular first-person pronouns and address readers as second person.
Language	Omit contractions.
Language	Avoid AISG terminology.
Formatting	Insert snippet for contributors at the top of your content.
Formatting	Adhere to PEP 8 for Markdown files (line lengths), code and Jupyter Notebooks.
Formatting	Use MyST flavour for Markdown documents. For notebooks, pair using Jupytext.
Formatting	Use sequential headings.
Formatting	Do not create TOCs manually.
Formatting	Present tables or figures inline after first mention.
Formatting	Credit references at the end of your content. Do not use in-text citations or bibliographies.

Structure

You may refer to this section for the appropriate directories which files and assets are to be placed under.

Repository Tree

The tree of the repository containing the book is structured as such:

ai-practitioner-handbook
    │
    ├── _config.yml     <-  YAML file detailing configurations for
    │                       Jupyter Book.
    ├── _toc.yml        <-  Configuration file that determines the
    │                       structure of the book.
    ├── .gitignore      <-  File for specifying files or directories
    │                       to be ignored by Git.
    ├── CHANGELOG.md    <-  Text file that lists changes made to the
    │                       project in chronological order.
    ├── CONTRIBUTING.md <-  File specifying conventions and formats
    │                       for contributors' reference.
    ├── README.md       <-  The top-level README containing basic
    │                       information of the project.
    ├── requirements.txt
    │                   ^-  File specifying dependencies needed to
    │                       generate the book.
    │
    ├── .github         <-  Folder (currently) housing workflow
    │                       definitions for GitHub Actions.
    └── book            <-  Directory containing book's contents and
        |                   assets.
        |── assets
        |               ^-  Directory containing non-text assets to be
        |                   referenced by the book.
        └── references.bib
                        ^-  Bibtext file containing citations and
                            bibliographies to be referenced by the book.

The files and directory that contributors will be mainly working with are the following:

_toc.yml
requirements.txt
book/**

Other files or directories are usually not to be modified unless required and requested by the core reviewers of the book.

Book Directory & Contents

Most contributions will be populating the book directory and mainly within directories pertaining to the different chapters.

Below describes each of the chapters and their respective subdirectories: