014 — Documentation

Documentation is one of the most important parts of Yii.

Package documentation

Documentation for a package could either be in README.md or docs/{language}/{type} where {language} is a language code and {type} could be "guide," "cookbook" or something else. Usually docs is there if the package usage or configuration isn't trivial or there's a need for translation.

Some indicators that it's time to create docs:

There is a need for translation.
Many topics exist. Each of these is big by itself.

If the total length of readme is less than about 200 lines, it's fine to keep documentation in the readme.

Definitive guide

The definitive guide, yiisoft/docs/guide aims at covering usage of packages as a whole framework. Unlike package documentation, it isn't focused on a single package but is covering certain use-cases.

The guide should follow Micosoft style guide.

Translation

The definitive guide uses po4a in GitHub Action for translations.

Translation algorithm:

Install an application for working with .po translation files. For example, Poedit, Lokalize, Gtranslator or another.
Find file what you want to translate in _translations/guide/{lang}. Note that if the source file is in a subfolder, the subfolder name is appended to the file name and separated by an underscore, for example, for translating guide/en/concept/aliases.md file find _translations/guide/{lang}/concept_aliases.md.po file.
Open the file with the .po extension in Poedit from the folder with the desired localization, for example _translations/guide/ru/intro_what-is-yii.md.po. If there is no localization yet, create an issue.
Translate necessary strings and push the changes
Open a pull request to the main repository

CAUTION

Do not change the translation in files in /guide/{lang} manually.

If you have changed English and want to update translations:

Open a pull request to the main repository
Pull updated branch after successful completion of workflow Update docs translation in GitHub Action
Update translation in .po files by Poedit
Push changes

Blocks

Blocks are in the GitHub Alerts format:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

When translating documentation, these Block indicators should not be translated. Keeps them intact as they are and only translate the block content. For translating the label for the block, each guide translation should have a blocktypes.json file containing the translations. The following shows an example for German:

json

{
    "Note": "Hinweis",
    "Tip": "Tipp",
    "Important": "Wichtig",
    "Warning": "Achtung",
    "Caution": "Vorsicht"
}

PHPDoc

PHPDoc mustn't be added if it doesn't add anything to what it describes. The following is a bad example:

php

use Psr\Log\LoggerInterface;

/**
 * MyService class
 */
final class MyService extends MyServiceBase
{
    /**
     * @var LoggerInterface logger 
     */
    private LoggerInterface $logger;

    /**
     * MyService constructor.
     * @param LoggerInterface $logger
     */
    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    /**
     * @inheritDoc
     */
    public function doit(): bool
    {
        return parent::doit();    
    }
}

PHPDoc, if present, should describe the purpose of the element it's added for.

Readme checklist

Each package readme should be placed into README.md and contain the following:

014 — Documentation ​

Package documentation ​

Definitive guide ​

Translation ​

Blocks ​

PHPDoc ​

Readme checklist ​