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:

  1. Create new issue

  2. Fill in issue details

  3. Open new feature branch with name chX-issueNum

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

  5. Submit pull request to main branch

1. Create a new issue#

image info

2. Fill in issue details#

image info

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 image info

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

image info

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 .

image info

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:

1. Pre-project Phase#

Directory Name: book/1-pre-project-phase

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

2. Project Management & Technical Leadership#

Directory Name: book/2-proj-mgmt-tech-lead

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

3. Collaborative Development Platforms#

Directory Name: book/3-collab-dev-platforms

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

4. Literature Review#

Directory Name: book/4-lit-review

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

5. Data Management, Exploration & Processing#

Directory Name: book/5-data-mgmt-exp-proc

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

6. Modelling#

Directory Name: book/6-modelling

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

7. Solution Delivery#

Directory Name: book/7-solution-delivery

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

8. Documentation & Handover#

Directory Name: book/8-documentation-handover

Synopsis: To be filled in…

Sections:

  • Section 1

  • Section 2

Any new chapters or sections (within a chapter) to be added are to be subjected to pull requests and further discussions and reviews. Sections within chapters are all to be structured in a flat manner and subdirectories are not to be used.

Content#

Here, we list down some pointers for you to keep in mind when formulating your content:

  • Do focus on content that can stand the test of time such as principles, strategies, design patters or digestible concepts.

  • In this field of work, tools come and go and become obsolete quite quickly so minimise references to any.

  • We aim to be concise but impactful so do limit the number of words to 500.

Language#

For consistency across all chapters, contributors are to stick to the usage of a single language: Singaporean Standard English, which is not much different from Standard British English.

Reviewers and contributors are to ensure correct grammar and consistent tone for contributions:

  • Your contents are to be presented in the form of a continuous prose.

  • Do use singular first-person pronouns. For example: “I suggest…”.

  • Do address readers as second person. Example: “you may encounter…”

  • Avoid contractions. Example: “let us” instead of “let’s”.

  • Avoid AISG-specific terminology, e.g., “100E”, “AI Apprentices”. Use neutral alternatives such as “AI/ML project” and “junior developers”, respectively, that a general, external audience can better understand.

This is a collective effort and everyone has a part to play in maintaining the quality of the book.

Reference(s):

Formatting#

This section details the format that contributors can refer to when contributing content and files to the book.

Contributors’ Credit#

For the content pieces you have worked on, do remember to insert the following snippet right after the header title with your name for proper crediting.

...
Contributor(s): <YOUR_NAME_HERE>, <ANOTHER_NAME_HERE>

---
...

PEP 8#

All documents like Markdown, sample code, or Jupyter Notebooks are to be subjected to the conventions laid out by PEP 8. Especially the maximum line length; limit all lines to a maximum of 72 characters. For code, the allowable maximum is 72 characters. However there are some exceptions like when links or Markdown tables are concerned.

You can configure your IDE’s or editor’s settings to set vertical rulers.

Reference(s):

Markdown Flavour#

This book treats Markdown files as first class citizens with regards to contents. Meaning: all of the book’s contents are to be strictly derived from MyST flavoured Markdown files. A contributor may formulate contents within Jupyter Notebooks (.ipynb files) but they would need to do the following:

  • Create the Jupyter Notebook under notebooks, under the appropriate subdirectory corresponding with the chapter it is meant for.

  • Its contents are to be converted out to a Markdown file. This can be done with Jupytext, through it’s paired notebooks functionality.

  • In this case, both the paired .md and .ipynb files are to be committed.

Headers#

When using headers, please do use them sequentially.

An example of inappropriate usage:

# Top Heading
### Section

Appropriate format:

# Top Heading
## Section

Table of Contents for Sections#

Since Jupyter Book automatically generates table of contents (TOCs) that appears on either side of the sidebars, manually written TOCs are unnecessary.

Figures & Tables#

Figures and tables are to be presented or inserted inline after it is first mentioned in main text. For example:

In the chart below, you would observe that the model is overfitted.

[Chart showing model overfitting](./book/assets/images/charts/example-chart.png)

The snippet above would yield the following results:

In the chart below, you would observe that the model is overfitted.

Chart showing model overfitting

Crediting References#

For any part of a content that references to external resources, you are to ensure that the resources are listed at the end of every document, like so:

__Reference(s):__

- [Jupyter Book Docs - Citations and bibliographies](https://jupyterbook.org/en/stable/content/citations.html#citations-and-bibliographies)
- [`sphinxcontrib-bibtex` Docs](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)

The snippet above would yield the following results:

Reference(s):

There will be no need for in-text citations and bibliography.