Size: a a a

DocOps-сообщество

2018 December 12

NV

Nick Volynkin in DocOps-сообщество
Timofey Zakrevskiy
не посыл, согласен. но одно из наблюдений
Люди будут отваливаться на каждом блоке, который им неинтересен или не по силам. И если сложное стоит перед простым, то до простого не дочитают.
источник

NV

Nick Volynkin in DocOps-сообщество
Причём сложность — это не единственный такой параметр. Ещё может быть специфика аудитории. Рассказывали такой кейс, уже не помню источник. Есть confluence, в нём статьи про фичи на уровне бизнесовых требований. Но в эти же статьи нужно вставить фрагменты кода. Если просто вставить код, то бизнесовые стейкхолдеры его видят и документ сразу закрывают. Решение: убрать код в разворачивающиеся блоки, по умолчанию их свернуть.
источник

TZ

Timofey Zakrevskiy in DocOps-сообщество
как бы то ни было, "воронка" - это "утрамбуем всех", а "сито" - это "часть отсеется, часть пройдёт дальше"
источник

ИЦ

Игорь Цупко in DocOps-сообщество
Timofey Zakrevskiy
как бы то ни было, "воронка" - это "утрамбуем всех", а "сито" - это "часть отсеется, часть пройдёт дальше"
воронка в том смысле, что часть отсеется - устаявшееся выражение.
см. "воронка продаж".
источник

TZ

Timofey Zakrevskiy in DocOps-сообщество
Игорь Цупко
воронка в том смысле, что часть отсеется - устаявшееся выражение.
см. "воронка продаж".
как бы то ни было, у человека, который не знаком с этим устоявшимся выражением, этот оборот вызывает недоумение
источник

I

Igor in DocOps-сообщество
Ну вот и познакомитесь с таким устоявшимся термином ;)
источник

FM

Fox Mulder in DocOps-сообщество
Можно побурчу
источник

FM

Fox Mulder in DocOps-сообщество
Нет никаких простых правил для документации
источник

FM

Fox Mulder in DocOps-сообщество
есть только два:
1. Деньги
2. Ресурсы
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Fox Mulder
есть только два:
1. Деньги
2. Ресурсы
Деньги тоже ресурс)
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
А внутренний ресурс сотрудников упирается в деньги

Иными словами, да, так можно всё свести к мысли "сколько разумно заплатить, такая и должна быть дока"

Но это не отвечает на вопросы, которые возникают, когда ресурс начинаешь использовать
источник

SL

Sergey Lystsev in DocOps-сообщество
Nick Volynkin
Что вы думаете про этот пост? Хочу мнений, критики, дополнений.
https://t.me/docops/214
Telegram
DocOps / Docs as code
​​Воронка технической сложности документа.
Прочитал статью про превью ссылок в Telegram. Статья хорошо выстроена по сложности и подаче материала.

Сначала смысл фичи объясняют как для ребёнка, буквально говорят, на какую кнопку нажать. А затем, от заголовка к заголовку, техническая сложность статьи повышается, так что до следующего заголовка дочитает всё меньше читателей. Это можно назвать воронкой технической сложности документа. (Только что придумал термин. Если это уже как-то названо — скажите, я поправлю.)

В целеполагании технического документа есть основные вопросы: кто читатель, какова цель читателя, какова цель бизнеса. Я уже разбирал их на примере комикса про Kubernetes. Давайте посмотрим на каждую главу этой статьи и ответим на эти вопросы. Заметьте, как от заголовка к заголовку сужается аудитория, меняется цель читателя, но строго выдерживается цель бизнеса.  

Instant Views Explained  
Для новичков. Задача читателя — наверное, удовлетворить любопытство. Задача бизнеса — чтобы читатели пользовались…
Мне кажется на первом шаге цели были немного другие. Читатель не просто удовлетворяет любопытство - он понимает, зачем ему это. Читатель здесь не пользователь телеграмма, а поставщик контента (пользователи просто кнопку жмут - им читать статью не надо). Бизнес здесь опять же ориентирован не на читателей, а на писателей. Надо заинтересовать писателей делать поддержку instant view. Читателей они заинтересовали наличием кнопки (им собственно и выбора то никто не давал).
источник

СФ

Семён Факторович in DocOps-сообщество
Vadim Smelyanskiy
А внутренний ресурс сотрудников упирается в деньги

Иными словами, да, так можно всё свести к мысли "сколько разумно заплатить, такая и должна быть дока"

Но это не отвечает на вопросы, которые возникают, когда ресурс начинаешь использовать
+1
источник

СФ

Семён Факторович in DocOps-сообщество
да, в бизнесе все упирается в деньги, но это осознание (или расчет каких-либо экономических метрик) не всегда помогает принимать тактические решения
источник

СФ

Семён Факторович in DocOps-сообщество
это примерно то же самое, как говорить, что все биологические процессы определяются законами неорганической химии или физики
источник

СФ

Семён Факторович in DocOps-сообщество
это так, но этот факт не очень помогает в объяснении биологических феноменов
источник

NV

Nick Volynkin in DocOps-сообщество
Sergey Lystsev
Мне кажется на первом шаге цели были немного другие. Читатель не просто удовлетворяет любопытство - он понимает, зачем ему это. Читатель здесь не пользователь телеграмма, а поставщик контента (пользователи просто кнопку жмут - им читать статью не надо). Бизнес здесь опять же ориентирован не на читателей, а на писателей. Надо заинтересовать писателей делать поддержку instant view. Читателей они заинтересовали наличием кнопки (им собственно и выбора то никто не давал).
Принято, дополню пост.
источник

SL

Sergey Lystsev in DocOps-сообщество
Семён Факторович
да, в бизнесе все упирается в деньги, но это осознание (или расчет каких-либо экономических метрик) не всегда помогает принимать тактические решения
Потому что деньги это "запаздывающий показатель" - они придут потом. А для принятия решений нужны "опережающие показатели" - что-то измеримое немедленно. Вот здесь бывший коллега понятно рассказывает https://www.youtube.com/watch?v=godkj5Zc-nw&fbclid=IwAR3EPoGAzT0UbBzlEVR71cNlqXu2Sv6jxF2yGXuryD6kyO0aF4vSvR7ULCo
источник

SL

Sergey Lystsev in DocOps-сообщество
Чтобы сделать деньги опережающим показателем, надо уметь более-менее объективно и быстро сравнивать монетарный результат изменения с результатом прошлой версии. booking.com умеет так делать для кода, не уверен, что и для документации они тоже так могут
источник

OI

Olga Ilchukova in DocOps-сообщество
так наконец-то прислушались к Fox (в большом чатике вас нет, пришлось зафорвардить в малый)
источник