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
- Shisho Developers (shisho.dev/docs): on our products
- Shisho Team Living Handbook (shisho.dev/handbook): on our team culture
- Our private GitHub monorepo: on all internal DevSecOps procedures, etc.
- Our private Confluence space: on all non-DevSecOps things, like business plans, sales procedures, and other company-wide internal documents
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
).
Helpers to Write Japanese Texts
Textlint preset
For texts written in Japanese, you can use our textlint preset (textlint-rule-preset-ja-shisho
).