Skip to main content

Documentation

The team is like software, and docs are like the software codes. This page describes why we write, who writes, where to write, and how to write.

Why We Write​

We value the power of documenting things around us. The background motivation is as follows:

  • be transparent by default; well-written documents let everyone in the team understand each other deeply, preventing them from jumping at shadows. Especially, public docs will be a foundation of trust with external stakeholders such as applicants or our customers.
  • get things organized; a process of writing a well-written document itself helps one to deepen their knowledge.

The team is like software ― documents correspond to software codes, and the team is at once the software developers and the software runtimes.

Who Writes​

When you do something, you're the best person to document it.

Where to Write​

How to Write​

We're moving (or trying to move) fast, the product is changing rapidly, and the team is still small compared to the current product needs ― this is the motivation for us to have some documentation helpers.

Helpers to Write English Texts​

Grammarly​

You can request a license when you need it.

Textlint preset​

For texts written in English, you can use our textlint preset (textlint-rule-preset-en-shisho). You have a Bazel rule textlint_en_test as well:

load("//scripts/bazel/docs:def.bzl", "textlint_en_test")

textlint_en_test(
    name = "en",
    srcs = glob(["**/*.md"]),
)

Helpers to Write Japanese Texts​

Textlint preset​

For texts written in Japanese, you can use our textlint preset (textlint-rule-preset-ja-shisho). You have a Bazel rule textlint_ja_test as well:

load("//scripts/bazel/docs:def.bzl", "textlint_ja_test")

textlint_ja_test(
    name = "ja",
    srcs = glob(["**/*.md"]),
)