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

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
   Из чего же сделаны наши стайлгайды?
   

   View Slide

2. • Семён Факторович
   • Руководитель отдела технической
   документации, Zodiac Novosibirsk
   • Старший преподаватель НГУ
   • Независимый консультант по
   вопросам документирования
   Кто здесь?
   

   View Slide

3. View Slide

4. View Slide

5. «как правильно»
   vs.
   «как принято у нас»
   

   View Slide

6. • Консистентность внутри одного файла
   • Единообразие всей кодовой базы
   • Best practices
   «Как принято у нас»
   

   View Slide

7. • Правила оформления
   • Локальные соглашения
   • Паттерны и антипаттерны
   Coding guidelines
   

   View Slide

8. • Правила оформления
   • Локальные соглашения
   • Паттерны и антипаттерны
   Coding guidelines
   +всевидящий компилятор
   

   View Slide

9. • Правила оформления
   • Локальные соглашения
   • Паттерны и антипаттерны
   Внутренний гид по стилю для документации
   

   View Slide

10. • Правила оформления
    • Локальные соглашения
    • Паттерны и антипаттерны
    Внутренний гид по стилю для документации
    +фундаментальные источники истины
    

    View Slide

11. View Slide

12. • Справочник по правописанию и стилистике
    Розенталя
    • Орфографический словарь на ваш вкус (gramota.ru)
    Фундаментальные источники истины
    

    View Slide

13. View Slide

14. • «Справочник издателя и автора» Мильчина и
    Чельцовой
    Фундаментальные источники истины
    

    View Slide

15. «Бранч» или «ветка»?
    

    View Slide

16. «Слияние» или «мерж»?
    

    View Slide

17. • Тоже является фундаментальным источником
    истины!
    Локальный глоссарий
    

    View Slide

18. View Slide

19. • Единый справочник по грамматике
    • Единый орфографический словарь (Merriam-
    Webster)
    • Google не подойдет!
    Иностранные языки
    

    View Slide

20. • The Chicago Manual of Style
    • Associated Press Stylebook
    Иностранные языки
    

    View Slide

21. • Фундаментальные источники истины
    • Повторение важных пунктов из ФИИ
    • Опровержения ФИИ
    • Локальные соглашения (включая глоссарий)
    Внутренний гид по стилю для документации
    

    View Slide

22. • «Где фундаментальные источники истины?»
    • «Твой текст нарушает пункт 14 нашего
    стайлгайда!»
    • Правила для автоматизированной проверки
    Гид по стилю: сценарии использования
    

    View Slide

23. • Консистентность внутри одного документа
    • Единообразие всей документационной базы
    Гид по стилю: зачем?
    

    View Slide

24. View Slide

25. Экономия времени команды!
    Гид по стилю: зачем?
    

    View Slide

26. • Microsoft Manual of Style
    • IEEE Editorial Style Manual
    • The Chicago Manual of Style
    • rdpk.ru
    Что почитать?
    

    View Slide

27. vk.com/sfactor
    www.documentat.io
    Семён Факторович
    sam.faktorovich@gmail.com
    Из чего же сделаны наши стайлгайды?
    

    View Slide