Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

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

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

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

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

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

More Decks by DocFactor: конференция о технической документации

Other Decks in Education

Transcript

  1. vk.com/sfactor
    www.documentat.io
    Семён Факторович
    [email protected]
    Из чего же сделаны наши стайлгайды?

    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
    Семён Факторович
    [email protected]
    Из чего же сделаны наши стайлгайды?

    View Slide