Size: a a a

KnowledgeConf Chat

2019 March 16

L

Lana in KnowledgeConf Chat
Olga Ilchukova
Я вижу в этой ситуации следующее. Тимлид осознал необходимость документирования и готов выделить отдельный ресурс под эту задачу. Это неплохой первый шаг к успеху, не каждый может этим похватстаться.

В качестве отдельного ресурса лучше сразу определить (найти, нанять, уговорить) технического писателя, человека, который знает, как и что писать, знает процессы документирования.

При этом тимлиду надо четко понимать, что техписатель — не подорожник. Даже если бы это был аналитик или кто-либо еще, то проблема бы не решилась только выделением ресурса. Если появилась новая для команды задача, то, вероятно, нужно с нуля внедрить процесс документирования. Техписатель это тот, кто может помочь с этим.

Да, к сожалению, в команде тимлида не укоренилась культура документирования. Тем не менее в новом процессе разработчикам все равно придется участвовать в качестве экспертов, помощников, консультантов. Как разработчикам участвовать во взаимодействии с техписателем, как раз и должен разрулить тимлид и укоренить это взаимодействие в правилах нового для команды процесса документирования.

Решение этой задачи мне видится таким.

Совмещение ролей аналитика и техписа не могу рассмотреть, потому что функциональное наполнение роли аналитика варьируется от команды к команде. Возможно, в команде этого тимлида аналитик глубоко укоренен в процесс разработки: проектирует, тестирует, экспериментирует с решениями, каждый день работает над фидбэком от пользователей и анализирует его с 100500 разных позиций. + в задаче не сказано об объеме задачи по документации. Возможно, там куча всего. Аналитик просто не вывезет.
Какой глубокий разбор, я бы ещё добавила, что лид пожинает плоды той культуры или ее отсутствия, которая сложилась до него
источник

OI

Olga Ilchukova in KnowledgeConf Chat
Lana
Какой глубокий разбор, я бы ещё добавила, что лид пожинает плоды той культуры или ее отсутствия, которая сложилась до него
да, безусловно. Полагаю, что возможно из-за того, что и сам лид не особо-то и документировал, ну или лид до него. Жаль, что такую культуру достаточно тяжело внедрить, но в целом это возможно.

Похожая тема есть с юнит-тестами. Бывает, что команда так же не понимает их необходимость, а потом при разрастании проекта утопает в пожарах.
источник

OI

Olga Ilchukova in KnowledgeConf Chat
Было бы интересно послушать решение, которое предложили тому тимлиду на конференции :)
источник

L

Lana in KnowledgeConf Chat
Olga Ilchukova
Было бы интересно послушать решение, которое предложили тому тимлиду на конференции :)
Решения будем придумывать и обсуждать на KnowledgeConf)) а на тимлид только болевые точки собирали)
источник

OI

Olga Ilchukova in KnowledgeConf Chat
ааааааа
источник
2019 March 18

L

Lana in KnowledgeConf Chat
Светлана Новикова поговорила с экипажем Podlodka по теме нашей конференции. Посмотрели на управление знаниями и со стороны инструментов, и со стороны процессов. В формате подкаста прошлись только по основным вопросам, а на KnowledgeConf сможем каждому уделить должное внимание.
https://soundcloud.com/podlodka/podlodka-103-upravlenie-znaniyami
источник
2019 March 19

IN

Igor Nabokov in KnowledgeConf Chat
всем привет.
У меня вопрос по поводу инструмента для внешней документации. Мы разрабатываем библиотеку для мобильных приложений и бэк для нее. Данный инструмент позволяет собирать телематические данные пользователя (если аккуратный водитель, то может получить скидку на страховку, например).

Для нашего продукта мы бы хотели создать документацию, которой будут пользоваться наши клиенты (компании, разрабатывающие мобильные приложения и желающие внедрить свою библиотеку). Ранее, мы передавали просто документы и библиотеку в архиве. Сейчас мы перешли на публикацию библиотеки в публичном доступе с автоматическим обновлением. Документацию пока выложили на тильде (простейший конструктор сайтов). Но там ее абсолютно неудобно править. Кроме того, она хранится либо только там, либо надо руками переносить из документов. Документы конечно же тоже устаревают.

На тимлид конф я подходил уже к Лане и к другим ребятам с вопросом внутренней документации. Решение хранить ее рядом с кодом (в том же markdown) и потом выгружать в конфлюенс, мне показалась удобной и интересной. Сейчас занимаюсь реализацией этого. Но как быть с внешней? Может есть какие-то инструменты, которые позволяют красиво и структурированно построить девелоперский портал?

Хорошими примерами таких порталов считаю следующие:
https://developer.here.com/documentation/ios-starter/dev_guide/topics/maps.html
https://developers.facebook.com/docs/facebook-login/ios
https://tech.yandex.ru/maps/doc/mapkit/3.x/concepts/about-docpage/
К сожалению, мы не можем заняться разработкой подобного портала с нуля, так как мы не яндекс и не фейсбук. Но готовы купить какое-то подходящее решение
источник

IN

Igor Nabokov in KnowledgeConf Chat
в поисках такого решения я пока натыкался лишь на сервисы документирования api, но этого нам недостаточно
источник

L

Lana in KnowledgeConf Chat
Igor Nabokov
всем привет.
У меня вопрос по поводу инструмента для внешней документации. Мы разрабатываем библиотеку для мобильных приложений и бэк для нее. Данный инструмент позволяет собирать телематические данные пользователя (если аккуратный водитель, то может получить скидку на страховку, например).

Для нашего продукта мы бы хотели создать документацию, которой будут пользоваться наши клиенты (компании, разрабатывающие мобильные приложения и желающие внедрить свою библиотеку). Ранее, мы передавали просто документы и библиотеку в архиве. Сейчас мы перешли на публикацию библиотеки в публичном доступе с автоматическим обновлением. Документацию пока выложили на тильде (простейший конструктор сайтов). Но там ее абсолютно неудобно править. Кроме того, она хранится либо только там, либо надо руками переносить из документов. Документы конечно же тоже устаревают.

На тимлид конф я подходил уже к Лане и к другим ребятам с вопросом внутренней документации. Решение хранить ее рядом с кодом (в том же markdown) и потом выгружать в конфлюенс, мне показалась удобной и интересной. Сейчас занимаюсь реализацией этого. Но как быть с внешней? Может есть какие-то инструменты, которые позволяют красиво и структурированно построить девелоперский портал?

Хорошими примерами таких порталов считаю следующие:
https://developer.here.com/documentation/ios-starter/dev_guide/topics/maps.html
https://developers.facebook.com/docs/facebook-login/ios
https://tech.yandex.ru/maps/doc/mapkit/3.x/concepts/about-docpage/
К сожалению, мы не можем заняться разработкой подобного портала с нуля, так как мы не яндекс и не фейсбук. Но готовы купить какое-то подходящее решение
Таких инструментов множество, например, мы используем RST+Sphinx с парочкой расширений, но нужно идти 1. от задач, какие элементы будут в доках 2. какой у вас стек, чтобы проще было под себя допиливать
источник

L

Lana in KnowledgeConf Chat
Вот неплохая подборка разных решений https://github.com/PharkMillups/beautiful-docs
источник

IN

Igor Nabokov in KnowledgeConf Chat
http://developer.raxeltelematics.com вот наш текущий вариант на тильде. Грубо говоря, нам надо описать, как подключить библиотеку к ios и android, как докрутить свой бэк, какие у нашего бэка есть методы api. Ну и какое-то схематичное описание в целом
источник

IN

Igor Nabokov in KnowledgeConf Chat
внутренняя документация в confluence
источник

L

Lana in KnowledgeConf Chat
Igor Nabokov
внутренняя документация в confluence
тогда Sphinx, Jekill, Mkdocs примерно все подходят
источник

IN

Igor Nabokov in KnowledgeConf Chat
с внутренней документацией я более менее разобрался, мне удалось добиться экспорта из rst туда
источник

IN

Igor Nabokov in KnowledgeConf Chat
я просто не представляю, подойдет ли confluence для внешней документации
источник

IN

Igor Nabokov in KnowledgeConf Chat
я понимаю, что sphinx может генерить статические html
источник

L

Lana in KnowledgeConf Chat
Igor Nabokov
я понимаю, что sphinx может генерить статические html
в частности, и еще какой-то набор таргетов, какие вам нужны, если нужны
источник

L

Lana in KnowledgeConf Chat
в конфлуэнс и пдф например умеет тоже
источник

IN

Igor Nabokov in KnowledgeConf Chat
но видимо пока не до конца разобрался с тем, какие там есть возможности по генерации чего-то целого с меню итп
источник

L

Lana in KnowledgeConf Chat
Igor Nabokov
но видимо пока не до конца разобрался с тем, какие там есть возможности по генерации чего-то целого с меню итп
там все допиливается темами поверх, css
источник