Google опубликовала руководство по оформлению документации для сторонних разработчиков

Google предоставила в свободный доступ руководство по соблюдению стиля, принятого в компании, при оформлении документации для проектов с открытым исходным кодом. Основной идеей данного руководства являются унификация и согласованность всей документации, поступающей от сторонних участников open-source проектов компании: Kubernetes, AMP и Dart.

Для чего нужно данное руководство?

Участники данных проектов получили прямой доступ к полезным советам по выбору стилистически правильных слов, словосочетаний, аббревиатур и даже тона голоса, используемого в видеодокументах, для соответствия стилю Google Developers. Руководство полезно как напоминание об использовании второго лица глагола, настоящего времени, активного залога, а также для проверки таких специфичных проблем, как написание «app» или же “application”.

Как им пользоваться?

Руководство представляет собой справочник, то есть нужные конструкции в нём можно искать прямым поиском. Например, при затруднениях с написанием пунктуационных знаков или созданием маркированных списков можно на странице поиска найти информацию по этим вопросам, просто написав необходимый запрос в панели навигации. Для поиска конкретных терминов и фраз можно воспользоваться данным списком.

Напутствие Google

Важно помнить, что данное руководство является лишь ориентиром хорошего тона, принятого в компании, а не драконовским правилом. В большинстве случаев у Google нет возможности и желания заставлять следовать этому руководству, особенно, когда оно не соответствует контексту документации. Но мы всё же надеемся, что вы поддержите наше стремление к повышению качества документации.