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

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

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

    • Старший преподаватель НГУ • Независимый консультант по вопросам документирования Кто здесь?
  3. None
  4. None
  5. «как правильно» vs. «как принято у нас»

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

    • Best practices «Как принято у нас»
  7. • Правила оформления • Локальные соглашения • Паттерны и антипаттерны

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

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

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

    Внутренний гид по стилю для документации +фундаментальные источники истины
  11. None
  12. • Справочник по правописанию и стилистике Розенталя • Орфографический словарь

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

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

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

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

  18. None
  19. • Единый справочник по грамматике • Единый орфографический словарь (Merriam-

    Webster) • Google не подойдет! Иностранные языки
  20. • The Chicago Manual of Style • Associated Press Stylebook

    Иностранные языки
  21. • Фундаментальные источники истины • Повторение важных пунктов из ФИИ

    • Опровержения ФИИ • Локальные соглашения (включая глоссарий) Внутренний гид по стилю для документации
  22. • «Где фундаментальные источники истины?» • «Твой текст нарушает пункт

    14 нашего стайлгайда!» • Правила для автоматизированной проверки Гид по стилю: сценарии использования
  23. • Консистентность внутри одного документа • Единообразие всей документационной базы

    Гид по стилю: зачем?
  24. None
  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 Из чего же сделаны наши

    стайлгайды?