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

2. bem-components:
документирование
блоков
Инна Белая
BEMup в Санкт-Петербурге, 6 сентября 2014

3. Инна Белая
neige@yandex-team.ru
@inna__neige
github.com/innabelaya
разработчик
технической
документации в Яндексе
3

4. Служба разработки технической
документации
4

5. Бригада документирования БЭМ
«За всё, что мы делаем, отвечать будем вместе!» (с)
5

6. Поговорим о
6

7. Поговорим о
где можно найти нашу документацию
6

8. Поговорим о
где можно найти нашу документацию
принципах разработки документации по БЭМ
6

9. Поговорим о
где можно найти нашу документацию
принципах разработки документации по БЭМ
как и что мы пишем
6

10. Поговорим о
где можно найти нашу документацию
принципах разработки документации по БЭМ
как и что мы пишем
почему нам важен ваш фидбек
6

11. Где найти документацию?
7

12. 8
Основные источники

13. 8
Основные источники
bem.info

14. 8
Основные источники
bem.info
https://github.com/bem/

15. 8
Основные источники
bem.info
https://github.com/bem/
Lego (внутренний сайт)

16. 9

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

18. Документация по БЭМ
11

19. Документация по БЭМ
принцип атомарных сущностей
11

20. Документация по БЭМ
принцип атомарных сущностей
документация – одна из реализаций блока
(технология наравне с JavaScript и CSS)
11

21. Документация по БЭМ
принцип атомарных сущностей
документация – одна из реализаций блока
(технология наравне с JavaScript и CSS)
параллельное хранение с кодом
11

22. Документация по БЭМ
принцип атомарных сущностей
документация – одна из реализаций блока
(технология наравне с JavaScript и CSS)
параллельное хранение с кодом
использует те же инструменты сборки
11

24. Порядок во всем

25. Преимущества подхода БЭМ
14

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

27. Преимущества подхода БЭМ
гибкое версионирование
прозрачная структура
14

28. Преимущества подхода БЭМ
гибкое версионирование
прозрачная структура
увеличение скорости разработки
14

29. Преимущества подхода БЭМ
гибкое версионирование
прозрачная структура
увеличение скорости разработки
быстрый поиск нужной информации
14

30. Что и как мы пишем?
15

31. Структура документации
16

32. Структура документации
16
JSDoc

33. Структура документации
16
JSDoc MarkDown

34. Структура документации
16
JSDoc MarkDown
*en.md

35. Структура документации
16
*ru.md *en.md
JSDoc MarkDown

36. Структура документации
16
*ru.md *en.md
JSDoc MarkDown
Примеры

37. Структура документации
16
*ru.md *en.md
JSDoc MarkDown
Примеры

38. Структура документации
16
*ru.md *en.md
JSDoc MarkDown
Примеры

39. Структура документации
16
*ru.md *en.md
JSDoc MarkDown
Примеры

40. Структура документации
16
*ru.md *en.md
JSDoc MarkDown
Документация к блоку
Примеры

41. JSDoc
17
JSDoc

42. JSDoc
описание публичных методов блока
17
JSDoc

43. JSDoc
описание публичных методов блока
документация от разработчиков
17
JSDoc

44. JSDoc
описание публичных методов блока
документация от разработчиков
собирается автоматически
17
JSDoc

45. JSDoc
описание публичных методов блока
документация от разработчиков
собирается автоматически
доступна только на английском языке
17
JSDoc

46. Пример
18

47. *ru.md *en.md
Описание блока
19
MarkDown

48. *ru.md *en.md
Описание блока
функциональные возможности блока
19
MarkDown

49. *ru.md *en.md
Описание блока
функциональные возможности блока
сферы применения
19
MarkDown

50. *ru.md *en.md
Описание блока
функциональные возможности блока
сферы применения
в формате MarkDown
19
MarkDown

51. *ru.md *en.md
Описание блока
функциональные возможности блока
сферы применения
в формате MarkDown
доступно на двух языках:
19
MarkDown

52. *ru.md *en.md
Описание блока
функциональные возможности блока
сферы применения
в формате MarkDown
доступно на двух языках:
русском
19
MarkDown

53. *ru.md *en.md
Описание блока
MarkDown
функциональные возможности блока
сферы применения
в формате MarkDown
доступно на двух языках:
русском
английском 19

54. 20
Пример

55. Примеры
21
Примеры

56. Примеры
живые примеры на сайте
21
Примеры

57. Примеры
живые примеры на сайте
BEMJSON каждого конкретного примера
21
Примеры

58. Примеры
живые примеры на сайте
BEMJSON каждого конкретного примера
отдельная вкладка для иллюстрации сложных
случаев
21
Примеры

59. 22
Пример примеров :)

60. 23
Пример примеров №2

61. Процесс разработки
документации
к bem-components
24

62. Создание
блока
Создание
issue
25

63. Создание
блока
Создание
issue
Анализ и
изучение
26

64. Создание
блока
Создание
issue
Анализ и
изучение
Работа с
командой
27

65. Создание
блока
Создание
issue
Анализ и
изучение
Работа с
командой
Описание
блока
28

66. Создание
блока
Создание
issue
Анализ и
изучение
Работа с
командой
Описание
блока
Pull
request
29

67. Создание
блока
Создание
issue
Анализ и
изучение
Работа с
командой
Описание
блока
Pull
request
Вычитка

68. Создание
блока
Создание
issue
Анализ и
изучение
Описание
блока
Работа с
командой
Pull
request
Вычитка Правки Повторная
вычитка
31

69. Создание
блока
Создание
issue
Анализ и
изучение
Описание
блока
Работа с
командой
Pull
request
Вычитка Правки Повторная
вычитка
Принятие
PR
32

70. Создание
блока
Создание
issue
Анализ и
изучение
Описание
блока
Работа с
командой
Pull
request
Вычитка Правки Повторная
Принятие
вычитка
PR
Проверка
в тестинге
33

71. Создание
блока
Создание
issue
Анализ и
изучение
Описание
блока
Работа с
командой
Pull
request
ВычитПкаравки Повторная
Проверка
в тестинге
Принятие
вычитка
PR
Публикация
на bem.info
34

72. Как найти нужный
документ?
35

73. 36
Способы поиска информации

74. Удобное меню
36
Способы поиска информации

75. Удобное меню
Поиск по сайту
36
Способы поиска информации

76. Удобное меню
Поиск по сайту
Теги
36
Способы поиска информации

77. ru.bem.info/forum/
37

78. ru.bem.info/forum/
37

79. ru.bem.info/forum/
37

80. ru.bem.info/forum/
37

81. Feedback в студию!
38

82. Нам важно ваше мнение
39

83. Любое ваше мнение
40

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

86. Анкета обратной связи
http://bit.ly/spb-feedback
!
!
43

87. 44
Инна Белая
Разработчик
технической
документации
bem.info
ru.bem.info/forum/
documentation libraries
!
neige@yandex-team.ru twitter.com/bem_ru