Документирование блоков. Раскрываем все плюсы Мы поговорим о том, как разрабатывается техническая документация к библиотеке bem-components и почему разделение интерфейса на блоки облегчает работу с документами как техническим писателям, так и разработчикам. А также о том, как мы выкладываем всю информацию по каждому блоку с примерами и JSDoc на наш сайт ru.bem.info. Инна Белая, Яндекс Разработчик технической документации в бригаде документирования БЭМ. В Яндексе с 2013 года.

2. Документирование блоков.
Раскрываем все плюсы
Инна Белая, разработчик технической документации

3. О чем поговорим
Документирование блоков. Раскрываем все плюсы 3

4. О чем поговорим
Где можно найти нашу документацию
Документирование блоков. Раскрываем все плюсы 3

5. О чем поговорим
Где можно найти нашу документацию
Как мы собираем документацию на сайт
Документирование блоков. Раскрываем все плюсы 3

6. О чем поговорим
Где можно найти нашу документацию
Как мы собираем документацию на сайт
Какие принципы мы используем для ее разработки
Документирование блоков. Раскрываем все плюсы 3

7. О чем поговорим
Где можно найти нашу документацию
Как мы собираем документацию на сайт
Какие принципы мы используем для ее разработки
Как и что мы пишем
Документирование блоков. Раскрываем все плюсы 3

8. Документирование блоков. Раскрываем все плюсы
Где найти документацию?

9. Основные источники
github.com/bem
Где найти документацию? 5

11. Основные источники
bem.info
Где найти документацию? 7

12. Документирование блоков. Раскрываем все плюсы
Процесс сборки и выкладки
документации

13. Инструменты
Процесс сборки и выкладки документации 9

14. Инструменты
github.com/bem/bem-site-engine
Процесс сборки и выкладки документации 9

15. Инструменты
github.com/bem/bem-site-engine
github.com/bem/bem-data-source
Процесс сборки и выкладки документации 9

16. Отображение на сайте
Процесс сборки и выкладки документации 10

17. bem.info – движок и сайт
Андрей Кузнецов

18. Плюшки
Процесс сборки и выкладки документации 12

19. Плюшки
Многоуровневая структура сайта
Процесс сборки и выкладки документации 12

20. Плюшки
Многоуровневая структура сайта
Контроль версий
Процесс сборки и выкладки документации 12

21. Плюшки
Многоуровневая структура сайта
Контроль версий
Переопределение ссылок
Процесс сборки и выкладки документации 12

22. Плюшки
Многоуровневая структура сайта
Контроль версий
Переопределение ссылок
Система тегов
Процесс сборки и выкладки документации 12

23. Плюшки
Многоуровневая структура сайта
Контроль версий
Переопределение ссылок
Система тегов
Лёгкость поддержки сайта с документацией
Процесс сборки и выкладки документации 12

24. Документирование блоков. Раскрываем все плюсы
Принципы разработки
документации по БЭМ

25. Базовые принципы
Принципы разработки документации по БЭМ 14

26. Базовые принципы
Принцип атомарных сущностей
Принципы разработки документации по БЭМ 14

27. Базовые принципы
Принцип атомарных сущностей
Документация – одна из реализаций блока
Принципы разработки документации по БЭМ 14

28. Базовые принципы
Принцип атомарных сущностей
Документация – одна из реализаций блока
Хранение рядом с кодом
Принципы разработки документации по БЭМ 14

29. Базовые принципы
Принцип атомарных сущностей
Документация – одна из реализаций блока
Хранение рядом с кодом
Гибкое версионирование
Принципы разработки документации по БЭМ 14

30. Базовые принципы
Принцип атомарных сущностей
Документация – одна из реализаций блока
Хранение рядом с кодом
Гибкое версионирование
Использование БЭМ-инструментов для сборки
Принципы разработки документации по БЭМ 14

31. Организация файловой системы
Принципы разработки документации по БЭМ 15

33. Порядок во всем
17

34. Документирование блоков. Раскрываем все плюсы
Что и как мы пишем?

35. Структура документации к блоку
Что и как мы пишем? 19

36. Структура документации к блоку
JSDoc
Что и как мы пишем? 19

37. Структура документации к блоку
JSDoc
Документация в формате MarkDown
Что и как мы пишем? 19

38. Структура документации к блоку
JSDoc
Документация в формате MarkDown
Инлайновые примеры
Что и как мы пишем? 19

39. JSDoc
Что и как мы пишем? 20

40. JSDoc
Автоматически собираемая документация
Что и как мы пишем? 20

41. JSDoc
Автоматически собираемая документация
Пишется разработчиками как комментарии в коде
Что и как мы пишем? 20

42. JSDoc
Автоматически собираемая документация
Пишется разработчиками как комментарии в коде
Содержит описание публичных методов блока
Что и как мы пишем? 20

43. JSDoc
Автоматически собираемая документация
Пишется разработчиками как комментарии в коде
Содержит описание публичных методов блока
Доступна только на английском языке
Что и как мы пишем? 20

44. Описание блока
Что и как мы пишем? 21

45. Описание блока
Содержит все функциональные возможности блока
Что и как мы пишем? 21

46. Описание блока
Содержит все функциональные возможности блока
Разрабатывается в формате MarkDown
Что и как мы пишем? 21

47. Описание блока
Содержит все функциональные возможности блока
Разрабатывается в формате MarkDown
Доступно на русском и английском языках
Что и как мы пишем? 21

48. Описание блока
Содержит все функциональные возможности блока
Разрабатывается в формате MarkDown
Доступно на русском и английском языках
Пишется техническими писателями совместно
с разработчиками
Что и как мы пишем? 21

49. Инлайновые примеры
Что и как мы пишем? 22

50. Инлайновые примеры
Пишутся непосредственно в описании блока
Что и как мы пишем? 22

51. Инлайновые примеры
Пишутся непосредственно в описании блока
Собираются на сайт автоматически
Что и как мы пишем? 22

52. Инлайновые примеры
Пишутся непосредственно в описании блока
Собираются на сайт автоматически
Предоставляют BEMJSON, HTML и наглядный пример для
каждого случая
Что и как мы пишем? 22

53. Исходный вид документации
Что и как мы пишем? 23

54. Отображение на сайте
Что и как мы пишем? 24

55. Документация на сайте bem.info
Что и как мы пишем? 25

56. Спасибо за внимание!

57. Контакты
Инна Белая
Разработчик технической документации
inna__neige@twitter
Документирование блоков. Раскрываем все плюсы 27