Из чего же сделаны наши стайлгайды? (Семён Факторович)

http://docfactor.ru
http://documentat.io

DocFactor'17, конференция о технической документации. 26 ноября 2017, Новосибирск, НГУ.

Из чего же сделаны наши стайлгайды? Семён Факторович, НГУ, documentat.io

Видео: https://www.youtube.com/watch?v=HzLWm2hhy3k

У программистов есть coding guidelines, у журналистов — редакционные политики, а что же есть у технических писателей? Правильно, внутренние гиды по стилю. Мы поговорим о том, какие задачи решает внутренний гид по стилю, почему он полезен не только документационной команде, с чего начать его создание и из каких кирпичиков его собирать.

Transcript

1. vk.com/sfactor www.documentat.io Семён Факторович sam.faktorovich@gmail.com Из чего же сделаны наши стайлгайды?
2. • Семён Факторович • Руководитель отдела технической документации, Zodiac Novosibirsk • Старший преподаватель НГУ • Независимый консультант по вопросам документирования Кто здесь?
5. «как правильно» vs. «как принято у нас»
6. • Консистентность внутри одного файла • Единообразие всей кодовой базы • Best practices «Как принято у нас»
7. • Правила оформления • Локальные соглашения • Паттерны и антипаттерны Coding guidelines
8. • Правила оформления • Локальные соглашения • Паттерны и антипаттерны Coding guidelines +всевидящий компилятор
9. • Правила оформления • Локальные соглашения • Паттерны и антипаттерны Внутренний гид по стилю для документации
10. • Правила оформления • Локальные соглашения • Паттерны и антипаттерны Внутренний гид по стилю для документации +фундаментальные источники истины
12. • Справочник по правописанию и стилистике Розенталя • Орфографический словарь на ваш вкус (gramota.ru) Фундаментальные источники истины
14. • «Справочник издателя и автора» Мильчина и Чельцовой Фундаментальные источники истины
15. «Бранч» или «ветка»?
16. «Слияние» или «мерж»?
17. • Тоже является фундаментальным источником истины! Локальный глоссарий
19. • Единый справочник по грамматике • Единый орфографический словарь (Merriam- Webster) • Google не подойдет! Иностранные языки
20. • The Chicago Manual of Style • Associated Press Stylebook Иностранные языки
21. • Фундаментальные источники истины • Повторение важных пунктов из ФИИ • Опровержения ФИИ • Локальные соглашения (включая глоссарий) Внутренний гид по стилю для документации
22. • «Где фундаментальные источники истины?» • «Твой текст нарушает пункт 14 нашего стайлгайда!» • Правила для автоматизированной проверки Гид по стилю: сценарии использования
23. • Консистентность внутри одного документа • Единообразие всей документационной базы Гид по стилю: зачем?
25. Экономия времени команды! Гид по стилю: зачем?
26. • Microsoft Manual of Style • IEEE Editorial Style Manual • The Chicago Manual of Style • rdpk.ru Что почитать?
27. vk.com/sfactor www.documentat.io Семён Факторович sam.faktorovich@gmail.com Из чего же сделаны наши стайлгайды?