Да, да, наверное, это примерно так, как я вижу (я не кодер, "половину слов не понял", но примерно догадываюсь). Ниже накатал простыню - не отсылаю к ней (экономьте свое время), но мне кажется, что разработка должна вестись от проекта как общей информационной модели. В терминах ООП (попытаюсь привести понятную кодеру аналогию) вы рассматриваете ПО как объект, строите его инф.модель примерно как класс, с этого "скелета" снимаете информацию о конкретной версии (та самая "абстракция над кодом"). Если у вас информация о проекте структурирована и лежит в одной базе (пока промолчу про интегрированные базы) - поддерживается и "актуальность", и "непротиворечивость", и можно выгрузить "что нужно в удобной форме". И можно использовать "от одной задачи к другой". Даже если у вас еще нет автоматизации уровня "БД с интерфейсом" - хотя бы начинать лежать в том направлении, грубо, уровня "отдельные таблички Эксель". Пока же выглядит так (может, я чего-то не понимаю), что "мы просто взяли кучу каких-то бумажных документов, описывающих проект, даже не полностью (по лохматым стандартам), а как показалось удобно, оцифровали, рассовали по папкам и вставили немножко ссылок". И вся эта бумага - вида "конструкторская документация для конструкторов". Там, кажется, нет даже документации типа "задание для исполнителя" (аналог "карта-наряд для рабочего"), хотя кодер уже не тот, кто "делает весь код по всему проекту", а по факту "рабочий, который пилит свой маленький кусочек и очень быстро". И предложение быстренькой-удобненькой автоматизации - давайте пустим к куче этой макулатуры ИИ, который на нее основе нам вероятностно нагенерит нужный текст. На полном серьезе.
Именно. Видите, я высказал свои мысли так, как мне было удобно (с температурой глухой ночью) и максимально подробно. Для меня этот лонгрид сырого текста удобен. Но если я изменю только форматирование - оно все равно останется непрочитанным лонгридом, на лонгрид время не тратят априори. Можно было бы написать совсем кратко - "нужно реальное решение - используйте имеющиеся скиллы". Что я тогда получу? 99% - игнор, 1% - вопрос "вы о чем" с долгим разжевыванием (т.е. лишнюю трату своего времени на выдачу того же текста, но кусками).
Пожалуйста, а можно пример? Какую-нибудь картинку, как по структуре, по оформлению должно выглядеть задание, которое вам будет удобно читать? Реально очень интересно.
Выскажу свои мысли, "почему" и "как наверное можно решить", но сразу предупрежу - они с очень специфической колокольни, и могут показаться глупыми, усложняющими и т.п. И в целом мои предположения как у "дефективной совы" - "мыши, станьте ежиками". Мне бы хотелось мыслей от работающих в отрасли ("да, это совсем глупости, потому что"). Возможно, я наивное дитя с крайнего чего-то там, который пришел к серьезным дядям, стал отвечать на риторические вопросы и на полном серьезе полез разбираться с идеями "сферических коней в вакууме" – тоже вариант. Но мне, правда, любопытно, "что творится-то". На всякий – никого не хочу обидеть или оскорбить. Острожно, лонгрид! Может, дело не в лени разработчиков и качестве отдельной документации, а в организации (в реализации автоматизации бизнес-процесса)? Нет, я не с критикой, не о том, что "у вас все плохо" - но если что-то не работает, может попробовать "зрить в корень" и поискать, "где собака зарыта"? Вы пишете о документации, как говорили в древности, "рабочего проекта". Рабочий проект - это описание информационной модели продукта, на основе которой делается продукт реальный. Общий тип процесса работает с древнейших времен и применяется даже вашими кодерами чуть не ежедневно. Чертеж и смета - документы проекта сарая, по ним строим сарай. Есть класс объекта - по нему делается конкретный объект (в ООП). И стиральную машинку на заводе тоже будут собирать примерно так же, единственное ключевое отличие - стиральную машинку вы какое-то время штампуете по утвержденной и не меняющейся документации на модель, потом конструкторам ставят новое задание (например, помечтаем, обратная связь от потребителей), они делают документацию на новую модель, и вы штампуете уже ее. А в современной разработке ПО процесс изменений почти постоянный, так что у вас конструкторское бюро, завод и отдел работы с заказчиками/потребителями "в одном флаконе". Когда продукт не сложный, пет-проект, стартап на 3 человек – это аналог "кустарного производства". Да, тут иногда срабатывает и "вообще без документации" – сарай можно построить и без чертежа, на глаз, из горы досок. И организация команды "Вася поговорил с Петей" отлично работает. Но современное ПО уже делается десятком разработчиков, с разделением ролей в команде, очень быстро. И организационно все превращено в "конвеер" (я не про "унизить разработчика", я о том, что при производстве сложного ПО, как и при производстве сложной техники, используют разделение труда). Задача ставится короткая и узкая – зато ее можно сделать быстро и потом собрать в общую работу (узнаете принцип?). И тут, признаться, я несколько впадаю в ступор. Я представляю, как производство стиральной машинки (а это довольно простая быт.техника) организовано так, что документация на нее лежит в... вики. И конструкторы правят все в... вики. И рабочего посылают смотреть, что ему делать, в... вики. Единой. Для всех. И, достижение – задание рабочего лежит в одной-двух страничках (как тут в комменте выше), а не в ста. Но современное ПО часто уже даже не стиральная машинка, а минимум автомобиль! Я представляю себе рабочего, которому дают не карту-наряд, где расписано: "берешь деталь А1, берешь гвоздь Б2 и молоток М3, вбиваешь гвоздь в отверстие 4 детали А1", а отсылают к талмуду на 100, а то и 1000 страниц, описывающему всю "машинку". Даже если талмуд не в одном файле с разделами, или с десятке документов, в структурированном формате вики. Рабочий пойдет читать? Даже если это прекрасно написанная, четкая и подробная документация, от которой все конструкторы в восторге? Нет. Не пойдет. Такая документация – прежде всего для конструкторов. Она не для рабочего – не та "целевая аудитория". И она описывает весь проект. В целом. А рабочему нужно не описание всей "стиральной машинки", а краткая инструкция (а "как гвозди типа Б вбиваются в детали типа А" – вот ссылка на раздел руководства, забудет – посмотрит). Я ни в коем случае не хочу унизить кодеров, сравнивая с рабочими. Я о том, что оба работают в дефиците ресурсов. Рабочему надо "быстро". Кодеру надо "быстро и кратко" – у него и релиз "горит", и информационный перегруз бывает. В чем по идее сложность по сравнению с "заводом"? Там документация меняется медленнее, потому тех.писатель написал инструкцию, потом подправил ее через несколько месяцев. Тут – быстро (иногда чуть не "утром заявка, через час правка, через два обновление"). Но смотрим на автоматизацию заводов, как у них стараются организовать. Информация об объекте (продукте, процессе) кладется в базу данных. И из базы, где хранится информационная модель объекта, данные выгружаются в конкретные документы по шаблонам. Мало того, системы, описывающие разные информационные модели продукта, интегрируются. А хранить в структурированных папках или вики – прикиньте, какой это примерно год или какие по размеру предприятия (и их продукты). То есть, с моей колокольни, "сапожнику надо подумать, как сшить себе домашние тапочки". А попросту – применить уже имеющиеся у вас в компании "скиллы" на практике. К себе. Причем у вас задачка в чем-то попроще – вы сами живете "внутри" бизнес-процесса, его участники и спецы, чтобы поправить – у вас под рукой. Если кодеры не читают документацию – для начала, может, хотя бы спросить, в каком виде им удобнее получать данные? Конкретно у вас, а не "в общем". Где затык? Объем? Форма? Подача? Содержание? Может, у вас разные "типы" кодеров по задачам – одним нужно "задание" в одном виде, другим "в другом". Посмотреть, проверить, что и им не нравится, на что уходит время. Может, неясно написано. Может, проблема в актуализации. Может вообще в какой-то мелочи – ну там "в вики шрифт слишком мелкий" (нет, сделать крупным – не факт что сами догадаются. "Не нравится документация" может на самом деле означать "не нравится интерфейс, потому стараюсь смотреть меньше / запоминаю хуже", проблема "неусвоения информации" может таиться и в таком). Я просто вспоминаю, что иногда проблемы и затыки на реальном производстве решались какими-то простейшими изменениями – стул поменяли, лампу передвинули; потом даже целую науку эргономику создали. А кто решает проблемы "затыков" с информацией? Бизнес- и системные аналитики, так вроде? А дальше примерно так же, как с автоматизацией заводов, которые когда-то были кустарными мастерскими с единичным выпуском (а где-то и сейчас есть, вроде "Тачки на прокачку"). Я не призываю ставить в мастерскую "с 2 калеками" ERP, и прыгать в автоматизации через 10 ступенек сходу. Но анализ узких мест и поиск проблем – это лохматейшая классика и скилл, который под рукой. Почему его не использовать, если действительно нужно решить проблему? (Да-да, "можно, а зачем?", "у меня времени нет / мне за это не платят", и "я просто пожаловаться, а ты всерьез, инопланетянин" – это я знаю :) ).
Она и без перетаскивания на ладан дышит, привет "реновации", заменяющей 5-этажки на 45-ти. Для местных, если вы не работаете кассиром в ближайшей П-ке, удаленка - это уже не прихоть, а средство выживания. Один несчастный ливень, снегопад - и на работу "на место" вовремя вы технически не попадете. Подмосковье? Сейчас, бывает, люди из дальнего быстрее электричками добираются через вокзал (дом - маршрутка до местной станции - вокзал - метро - работа), чем живущие в застраиваемых "спальниках" или в ближнем, пытаясь добраться маршрутками-наземкой до окраинного метро и втиснуться в него.
А у меня те, кто физически не смогут без покупки нового железа. У них вообще альтернативы нет - все кроме ТГ заблочили, мах не ставится, вк-мессенджер отвалится вместе с очередным обновлением. Заблочат ТГ - идти новый прибамбас покупать? Это как раз те самые "бабушки", у которых на новый смарт денег нету. И которым дешевле заплатить "внучку" за установку чего-нибудь для обхода. Потому что, кроме ТГ, у них еще куча всего посыпалась из-за "белых списков" (см. соседние статьи) - если какой-нибудь сайт с безобидным вязанием висел на зарубежном хостинге, теперь "не открывается, поможи". И "внучок" поставит. Чего-нибудь. Со всеми вытекающими сливами данных. Вот такая "защита от мошенников" выходит.
Прошу прощения, что вмешиваюсь (я не топик-стартер), но вы не могли бы уточнить, что вы подразумеваете под "форматом" и "базой знаний"? "Формат" - это для вас формат структуры данных конкретного документа или формат структуры (формат ведения) всей документации? "База знаний" - это БД, из которой вы хотите сделать продвинутую аналитическую и статистическую обработку данных, или? Просто автор, как понимаю, тех.писатель, а у вас более технический и очень узкий вопрос. И ответ на него зависит от многих факторов: какая у вас документация, какие объемы данных, где они уже хранятся, что вы собираетесь с ними делать и зачем. Это скорее системно-архитектурный вопрос, а архитектура может быть очень разная. Так что без подробного уточнения вам даже никто не скажет, к кому вам хотя бы примерно с таким вопросом обращаться, чтобы получить релевантный ответ. (Да, я, увы, тоже вряд ли помогу, кроме "распишите подробнее, что вам нужно". Можно попробовать уточнить у бесплатного АИ, что сейчас примерно "покрывает" ваши требования, и тогда тут искать спецов в этой теме и спрашивать. Но с тем же "расширенным вопросом" - "вот у меня есть то и то, хочу то и то, не могли бы вы посоветовать, в каком формате мне лучше делать документацию, чтобы потом можно было". Тут даже лучше не формулировать "оптимально" - с такой точностью вам ответят только за очень большие деньги после тщательного обследования "что у вас").
Соглашусь, в целом да. Для кофе критично, для массмаркетного чая - критично, а вот как раз хороший (не обязательно сверхдорогой) китайский зеленый чай может быть из категории "лао", встречаются, например, 12 или даже 20-летнего срока хранения. При исходно хорошем сырье и приличном хранении (в глухой упаковке) не могу сказать, что качество падает и чай становится "сеном" - нет, он просто становится другим. И, конечно, такой чай лучше заваривать именно чайным мастерам. Но если у вас на дальней полке затерялась коробка не вскрытого китайского чая "еще с рынка" 10+ лет давности, не спешите выбрасывать как "точно мусор". Там может оказаться что-то очень интересное (по крайней мере тем же любителям китайского чая).
Простите, но у меня написано о ЦА не вашей статьи, а ЦА именно документации, и даже развернуто подробно, почему это важно. Даже ребенка лучше сразу учить правильно, а не "потом поправим". Документация "для коллеги", "для пользователя" и "для (потенциального) заказчика" может вообще называться одинаково, например какое-нибудь "описание программы", но это будут совершенно разные документы, разного объема, структуры и стиля изложения. Потому что, условно, первое - часть рабочего проекта, второе - краткое пояснение пользователю, с чем он работает, а третье - контент для выкладки на сайт.
И... простите, я, наверное, немного отстаю от жизни.Опять же не критика, а интересно. "Разработчик или тестировщик берутся за документацию не от хорошей жизни и обычно не знают, с чего начать". Простите великодушно, я понимаю, что разраб огромной корпорации огромного проекта может документировать только свой мелкий кусочек работы - ему дали задание, он выполнил и поставил галочку. Но у него тогда все процессы выверены, и если ему придет задача "напиши инструкцию", то с ней должен прийти и шаблон, а проверяющий техпис все равно вычитает, отредактирует и поправит. Иначе его кусочек ни в общую документацию не уложится, ни проверку качества не пройдет - потому что "чукча читатель, а не техписатель". Но у вас вроде бы пример другого кейса, где команда маленькая, и каждый поневоле "и швец и жнец". Но в такой команде каждый, напрямую, фактически имеет доступ ко всей документации, мало того - она никак не создается без общей кооперации! Так что значит "не от хорошей жизни"? Это как раз "хорошая жизнь" микрокоманды - один, например, совмещает обязанности сист.аналитика и шеф-тех.писа, делает структуру документации, прикидывает объем, пишет важные документы вроде ТЗ; джуны-техписы "на подхвате", а остальным перепадает писать те разделы, в которых они разбираются. И даже в такой команде будет и структура документации, и задания. А не бардак и непонятная "личная инициатива". Вот написанная разработчиком инициативно инструкция, она зачем нужна? Ее нет в спецификации документов, которые мы должны дать заказчику. Ее нет в структуре рабочего проекта. Наверное, начинается с "ребят, вам инструкцию написать?", одобрения ведущего доки, месте под нее в структуре проекта (вот эта инструкция привязана к этой версии), шаблона, а не "я принес документ, дайте мне плюсик в карму". Иначе это работа на увеличение энтропии и мусора в доках и "на минусик в карму". Или у вас тот самый кейс "у нас эджайл, нам вообще никакая документация не нужна, пока не приперло, а вот приперло - срочно напишите"? Так там с другого по идее надо начинать, иначе вообще все похороните в авгиевых конюшнях...
Простите, без сарказма и критики - немного путаюсь в ваших терминах "документация" и "статья" и не немного понимаю, вы про документацию или про некий контент, который хотите где-то опубликовать (на Хабре, на сайте компании, в личном блоге) или кому-то дать почитать?
Опять же не как критика. По моему некоторому опыту, все же первое, с чего следует начинать - это "целевая аудитория". Новому сотруднику компании, потенциальным покупателям продукта и коллегам на выставке нужна совершенно разная информация, о разных вещах, с разными целями, в разном объеме и рассказанная доступным им языком. Смотрите, даже тут на Хабре в каждой статье указывается ключевое - "сложность", время на прочтение и даны теги, кратко характеризующие "о чем". Поэтому сперва надо определиться - кто читатель? Что ему (потенциально) нужно / что вы хотите сообщить и о чем? Для чего и, следовательно, в каком объеме? Эти ответы сразу определят вид "документации". Это краткая инструкция или полное руководство? Это рекламный проспект или статья для коллег-спецов? Вид определяет форму, структуру, подачу материала. Человечество пишет уже тысячи лет, так что вам не придется изобретать велосипед. Вам нужно красиво расписать достоинства товара? Вам к маркетологам и рекламщикам в стыке с психологами и дизайнерами, с соответствующим запросом (условному гуглу)"как написать рекламный буклет, чтобы он понравился" или условному промпту ЛЛМке "рекламный буклет для такого-то товара для мужика 30-40 лет такого-то уровня дохода, в таком-то стиле, чтобы привлечь внимание к товару / создать положительное впечатление..." и т.п.. Использование лит.приемов и игры слов здесь не баг, а фича! Вы работайте с гоской, или, о ужас, внезапно с военкой? Вам нужен тамошний канцлярит и стандарты (например ЕСПД), и тщательная выверка вплоть до запятых - иначе вас не воспримут всерьез. И, да, это тавтологии и применение слов, принятых "по стандарту", а не "как все называют", даже если это звучит буквально допотопно. У вас новый сотрудник - студент, который первый раз такое вижу" или крутой спец "дайте покопаться под капотом"? Им нужен разный объем информации и в разном изложении. У вас "спец в поле" - как было тут в комментах выше? Такому спецу нужна инструкция, которую удобно загнать прямо в смартфон, где все по шагам с маркерами, а идеально - с иллюстрациями или "примечаниями" по ссылкам прямо в "шаге": понадобилось, ткнул ссылку, посмотрел, вернулся. Здесь условия использования определяют форму, форма - изложение контента. Никаких длинных фраз. Никаких пространных уточнений - их при необходимости в примечания.
Да, я помню, что статья "для самых маленьких", а я пугаю "маркетологами" и страшным словом "ЕСПД". Но давайте сразу определим правильное направление, "куда лежать". "У нас Эджайл, нам продукт важнее документирования!" - ровно до тех пор, пока у вас один из команды не уволился. Или, тьфу-тьфу, не заболел или не произошел несчастный случай (всякое бывает). Потому для вас все начинается с "сколько необходимо и достаточно, чтобы новый сотрудник быстро вошел в курс дела", а не был вынужден "расшифровывать легаси". Не "мы продвинутые и напишем красиво и молодежно (понятно нам), мы что, динозавры?!" - а "зубодробительно и в стиле аж 70х, но понятно и приятно госке". Тогда вам не придется переделывать, теряя в репутации ("ох уж эти школяры-вайтишники!") - уже скачанный из инета шаблон сразу идет вам в плюсик, а стиль ЛЛМка при необходимости выправит. И пара местных хабровских статей маркетологов (а то и древних книжек "по рекламе") вам для "рекламного буклета" поможет больше, чем попытка "в лоб" использовать жи-пи-чат: на нейронки и их "натворения" у всех скоро будет "баннерная слепота".
Спасибо за статью, в целом мысль правильная и картинки очень милые!
Я вот с сабами смотрю, чтобы слышать оригинальную озвучку, так когда саб на "черной полосе", а не на картинке - это прям отлично! И кадр тоже предпочитаю видеть "как задумал автор" - вам может что-то и "лишнее", а мне детали рассматривать бывает интересно, интерьер, пейзажи. Вы, например, знаете, что англичанин, посмотревший нашего "Холмса", говорил про детали интерьера: "такие же штуки были у моей бабушки"?
1) Кофе и чай - это не чистые аптечные таблетки, где точно указана доза кофеина, это "экстракт" из растительного сырья, полученный "кустарным" способом. Смесь сложных химических веществ, которую вы получаете в чашке, может разительно отличаться в зависимости от вида и качества сырья (индийский массмаркетный зеленый чай в пакетиках и какой-нибудь приличный рассыпной китайский, как и дешевая массмаркетная робуста и приличная арабика - это совершенно разные вещи не только по вкусу, но и по тому же содержанию кофеина), от способа приготовления (заваренный кипятком "чифирь" против китайского пролива, растянутого на час, фильтр-кофе против эспрессо... промолчу про ристретто) и даже от качества и температуры воды (поговорите как-нибудь с хорошим чайным мастером в китайской чайной, узнаете много удивительного). Эффект даже от кофе из двух пачек одной цены разных фирм из ближайшего магазина, или "чистого" американо и точно такого же с молоком может быть разным, с чаем бывает еще сложней. Хотите попробовать усилить эффект от чая или кофе? Не обязательно добавлять больше: используйте "более тонкий помол" (кофе "для кружки" с помолом "в пыль"), заварите почти кипятком (в обычных условиях зеленый чай все же принято заваривать горячей водой, а кофе "в турке" - не кипятить) или используйте "жесткую" воду (можно просто добавить чуть соли) - это усилит экстракцию, но скажется на вкусе. Хотите смягчить и растянуть эффект? Добавьте молоко или сливки.
2) На полученную сложную химическую смесь у каждого человека индивидуальная реакция. Кто-то от кофе (или китайского шу пуэра) просыпается, кто-то, напротив, засыпает; кому-то зеленый чай вообще как "вода" с нулем эффекта. Какой эффект получите от конкретного напитка лично вы - узнать только опытным путем :) Но соблюдайте ТБ любого эксперимента. Есть гипотоники, есть гипертоники, есть язвенники. Никакой новый напиток желательно не пробовать натощак. Если у вас явные проблемы с АД - перед "а попробую-ка я ристретто из этой дешевенькой робусты" (или "вот этот элитный китайский чай") запаситесь тонометром и лекарством: в чашке может отказаться не "безопасная ароматизированно-подкрашенная водичка", а нечто с такой ядреной (индивидуально для вас) концентрацией, что буквально на глазах (по бегущим циферкам на браслете тонометра) словите криз. А если "чай с добавками для бодрости", а вы аллергик - антигистаминным, и пробуйте малыми дозами, аккуратно.
Да, да, наверное, это примерно так, как я вижу (я не кодер, "половину слов не понял", но примерно догадываюсь). Ниже накатал простыню - не отсылаю к ней (экономьте свое время), но мне кажется, что разработка должна вестись от проекта как общей информационной модели. В терминах ООП (попытаюсь привести понятную кодеру аналогию) вы рассматриваете ПО как объект, строите его инф.модель примерно как класс, с этого "скелета" снимаете информацию о конкретной версии (та самая "абстракция над кодом"). Если у вас информация о проекте структурирована и лежит в одной базе (пока промолчу про интегрированные базы) - поддерживается и "актуальность", и "непротиворечивость", и можно выгрузить "что нужно в удобной форме". И можно использовать "от одной задачи к другой". Даже если у вас еще нет автоматизации уровня "БД с интерфейсом" - хотя бы начинать лежать в том направлении, грубо, уровня "отдельные таблички Эксель". Пока же выглядит так (может, я чего-то не понимаю), что "мы просто взяли кучу каких-то бумажных документов, описывающих проект, даже не полностью (по лохматым стандартам), а как показалось удобно, оцифровали, рассовали по папкам и вставили немножко ссылок". И вся эта бумага - вида "конструкторская документация для конструкторов". Там, кажется, нет даже документации типа "задание для исполнителя" (аналог "карта-наряд для рабочего"), хотя кодер уже не тот, кто "делает весь код по всему проекту", а по факту "рабочий, который пилит свой маленький кусочек и очень быстро". И предложение быстренькой-удобненькой автоматизации - давайте пустим к куче этой макулатуры ИИ, который на нее основе нам вероятностно нагенерит нужный текст. На полном серьезе.
Именно. Видите, я высказал свои мысли так, как мне было удобно (с температурой глухой ночью) и максимально подробно. Для меня этот лонгрид сырого текста удобен. Но если я изменю только форматирование - оно все равно останется непрочитанным лонгридом, на лонгрид время не тратят априори. Можно было бы написать совсем кратко - "нужно реальное решение - используйте имеющиеся скиллы". Что я тогда получу? 99% - игнор, 1% - вопрос "вы о чем" с долгим разжевыванием (т.е. лишнюю трату своего времени на выдачу того же текста, но кусками).
Пожалуйста, а можно пример? Какую-нибудь картинку, как по структуре, по оформлению должно выглядеть задание, которое вам будет удобно читать? Реально очень интересно.
Выскажу свои мысли, "почему" и "как наверное можно решить", но сразу предупрежу - они с очень специфической колокольни, и могут показаться глупыми, усложняющими и т.п. И в целом мои предположения как у "дефективной совы" - "мыши, станьте ежиками". Мне бы хотелось мыслей от работающих в отрасли ("да, это совсем глупости, потому что"). Возможно, я наивное дитя с крайнего чего-то там, который пришел к серьезным дядям, стал отвечать на риторические вопросы и на полном серьезе полез разбираться с идеями "сферических коней в вакууме" – тоже вариант. Но мне, правда, любопытно, "что творится-то". На всякий – никого не хочу обидеть или оскорбить. Острожно, лонгрид!
Может, дело не в лени разработчиков и качестве отдельной документации, а в организации (в реализации автоматизации бизнес-процесса)? Нет, я не с критикой, не о том, что "у вас все плохо" - но если что-то не работает, может попробовать "зрить в корень" и поискать, "где собака зарыта"?
Вы пишете о документации, как говорили в древности, "рабочего проекта". Рабочий проект - это описание информационной модели продукта, на основе которой делается продукт реальный. Общий тип процесса работает с древнейших времен и применяется даже вашими кодерами чуть не ежедневно. Чертеж и смета - документы проекта сарая, по ним строим сарай. Есть класс объекта - по нему делается конкретный объект (в ООП). И стиральную машинку на заводе тоже будут собирать примерно так же, единственное ключевое отличие - стиральную машинку вы какое-то время штампуете по утвержденной и не меняющейся документации на модель, потом конструкторам ставят новое задание (например, помечтаем, обратная связь от потребителей), они делают документацию на новую модель, и вы штампуете уже ее. А в современной разработке ПО процесс изменений почти постоянный, так что у вас конструкторское бюро, завод и отдел работы с заказчиками/потребителями "в одном флаконе".
Когда продукт не сложный, пет-проект, стартап на 3 человек – это аналог "кустарного производства". Да, тут иногда срабатывает и "вообще без документации" – сарай можно построить и без чертежа, на глаз, из горы досок. И организация команды "Вася поговорил с Петей" отлично работает. Но современное ПО уже делается десятком разработчиков, с разделением ролей в команде, очень быстро. И организационно все превращено в "конвеер" (я не про "унизить разработчика", я о том, что при производстве сложного ПО, как и при производстве сложной техники, используют разделение труда). Задача ставится короткая и узкая – зато ее можно сделать быстро и потом собрать в общую работу (узнаете принцип?).
И тут, признаться, я несколько впадаю в ступор. Я представляю, как производство стиральной машинки (а это довольно простая быт.техника) организовано так, что документация на нее лежит в... вики. И конструкторы правят все в... вики. И рабочего посылают смотреть, что ему делать, в... вики. Единой. Для всех. И, достижение – задание рабочего лежит в одной-двух страничках (как тут в комменте выше), а не в ста. Но современное ПО часто уже даже не стиральная машинка, а минимум автомобиль!
Я представляю себе рабочего, которому дают не карту-наряд, где расписано: "берешь деталь А1, берешь гвоздь Б2 и молоток М3, вбиваешь гвоздь в отверстие 4 детали А1", а отсылают к талмуду на 100, а то и 1000 страниц, описывающему всю "машинку". Даже если талмуд не в одном файле с разделами, или с десятке документов, в структурированном формате вики. Рабочий пойдет читать? Даже если это прекрасно написанная, четкая и подробная документация, от которой все конструкторы в восторге? Нет. Не пойдет. Такая документация – прежде всего для конструкторов. Она не для рабочего – не та "целевая аудитория". И она описывает весь проект. В целом. А рабочему нужно не описание всей "стиральной машинки", а краткая инструкция (а "как гвозди типа Б вбиваются в детали типа А" – вот ссылка на раздел руководства, забудет – посмотрит).
Я ни в коем случае не хочу унизить кодеров, сравнивая с рабочими. Я о том, что оба работают в дефиците ресурсов. Рабочему надо "быстро". Кодеру надо "быстро и кратко" – у него и релиз "горит", и информационный перегруз бывает.
В чем по идее сложность по сравнению с "заводом"? Там документация меняется медленнее, потому тех.писатель написал инструкцию, потом подправил ее через несколько месяцев. Тут – быстро (иногда чуть не "утром заявка, через час правка, через два обновление"). Но смотрим на автоматизацию заводов, как у них стараются организовать. Информация об объекте (продукте, процессе) кладется в базу данных. И из базы, где хранится информационная модель объекта, данные выгружаются в конкретные документы по шаблонам. Мало того, системы, описывающие разные информационные модели продукта, интегрируются. А хранить в структурированных папках или вики – прикиньте, какой это примерно год или какие по размеру предприятия (и их продукты).
То есть, с моей колокольни, "сапожнику надо подумать, как сшить себе домашние тапочки". А попросту – применить уже имеющиеся у вас в компании "скиллы" на практике. К себе. Причем у вас задачка в чем-то попроще – вы сами живете "внутри" бизнес-процесса, его участники и спецы, чтобы поправить – у вас под рукой.
Если кодеры не читают документацию – для начала, может, хотя бы спросить, в каком виде им удобнее получать данные? Конкретно у вас, а не "в общем". Где затык? Объем? Форма? Подача? Содержание? Может, у вас разные "типы" кодеров по задачам – одним нужно "задание" в одном виде, другим "в другом". Посмотреть, проверить, что и им не нравится, на что уходит время. Может, неясно написано. Может, проблема в актуализации. Может вообще в какой-то мелочи – ну там "в вики шрифт слишком мелкий" (нет, сделать крупным – не факт что сами догадаются. "Не нравится документация" может на самом деле означать "не нравится интерфейс, потому стараюсь смотреть меньше / запоминаю хуже", проблема "неусвоения информации" может таиться и в таком). Я просто вспоминаю, что иногда проблемы и затыки на реальном производстве решались какими-то простейшими изменениями – стул поменяли, лампу передвинули; потом даже целую науку эргономику создали. А кто решает проблемы "затыков" с информацией? Бизнес- и системные аналитики, так вроде?
А дальше примерно так же, как с автоматизацией заводов, которые когда-то были кустарными мастерскими с единичным выпуском (а где-то и сейчас есть, вроде "Тачки на прокачку"). Я не призываю ставить в мастерскую "с 2 калеками" ERP, и прыгать в автоматизации через 10 ступенек сходу. Но анализ узких мест и поиск проблем – это лохматейшая классика и скилл, который под рукой. Почему его не использовать, если действительно нужно решить проблему? (Да-да, "можно, а зачем?", "у меня времени нет / мне за это не платят", и "я просто пожаловаться, а ты всерьез, инопланетянин" – это я знаю :) ).
Она и без перетаскивания на ладан дышит, привет "реновации", заменяющей 5-этажки на 45-ти. Для местных, если вы не работаете кассиром в ближайшей П-ке, удаленка - это уже не прихоть, а средство выживания. Один несчастный ливень, снегопад - и на работу "на место" вовремя вы технически не попадете. Подмосковье? Сейчас, бывает, люди из дальнего быстрее электричками добираются через вокзал (дом - маршрутка до местной станции - вокзал - метро - работа), чем живущие в застраиваемых "спальниках" или в ближнем, пытаясь добраться маршрутками-наземкой до окраинного метро и втиснуться в него.
А у меня те, кто физически не смогут без покупки нового железа. У них вообще альтернативы нет - все кроме ТГ заблочили, мах не ставится, вк-мессенджер отвалится вместе с очередным обновлением. Заблочат ТГ - идти новый прибамбас покупать? Это как раз те самые "бабушки", у которых на новый смарт денег нету. И которым дешевле заплатить "внучку" за установку чего-нибудь для обхода. Потому что, кроме ТГ, у них еще куча всего посыпалась из-за "белых списков" (см. соседние статьи) - если какой-нибудь сайт с безобидным вязанием висел на зарубежном хостинге, теперь "не открывается, поможи". И "внучок" поставит. Чего-нибудь. Со всеми вытекающими сливами данных. Вот такая "защита от мошенников" выходит.
Мыл-агент забыли. Вполне рабочий в свое время был. И где?
Прошу прощения, что вмешиваюсь (я не топик-стартер), но вы не могли бы уточнить, что вы подразумеваете под "форматом" и "базой знаний"? "Формат" - это для вас формат структуры данных конкретного документа или формат структуры (формат ведения) всей документации? "База знаний" - это БД, из которой вы хотите сделать продвинутую аналитическую и статистическую обработку данных, или? Просто автор, как понимаю, тех.писатель, а у вас более технический и очень узкий вопрос. И ответ на него зависит от многих факторов: какая у вас документация, какие объемы данных, где они уже хранятся, что вы собираетесь с ними делать и зачем. Это скорее системно-архитектурный вопрос, а архитектура может быть очень разная. Так что без подробного уточнения вам даже никто не скажет, к кому вам хотя бы примерно с таким вопросом обращаться, чтобы получить релевантный ответ. (Да, я, увы, тоже вряд ли помогу, кроме "распишите подробнее, что вам нужно". Можно попробовать уточнить у бесплатного АИ, что сейчас примерно "покрывает" ваши требования, и тогда тут искать спецов в этой теме и спрашивать. Но с тем же "расширенным вопросом" - "вот у меня есть то и то, хочу то и то, не могли бы вы посоветовать, в каком формате мне лучше делать документацию, чтобы потом можно было". Тут даже лучше не формулировать "оптимально" - с такой точностью вам ответят только за очень большие деньги после тщательного обследования "что у вас").
Соглашусь, в целом да. Для кофе критично, для массмаркетного чая - критично, а вот как раз хороший (не обязательно сверхдорогой) китайский зеленый чай может быть из категории "лао", встречаются, например, 12 или даже 20-летнего срока хранения. При исходно хорошем сырье и приличном хранении (в глухой упаковке) не могу сказать, что качество падает и чай становится "сеном" - нет, он просто становится другим. И, конечно, такой чай лучше заваривать именно чайным мастерам. Но если у вас на дальней полке затерялась коробка не вскрытого китайского чая "еще с рынка" 10+ лет давности, не спешите выбрасывать как "точно мусор". Там может оказаться что-то очень интересное (по крайней мере тем же любителям китайского чая).
Простите, но у меня написано о ЦА не вашей статьи, а ЦА именно документации, и даже развернуто подробно, почему это важно. Даже ребенка лучше сразу учить правильно, а не "потом поправим". Документация "для коллеги", "для пользователя" и "для (потенциального) заказчика" может вообще называться одинаково, например какое-нибудь "описание программы", но это будут совершенно разные документы, разного объема, структуры и стиля изложения. Потому что, условно, первое - часть рабочего проекта, второе - краткое пояснение пользователю, с чем он работает, а третье - контент для выкладки на сайт.
И... простите, я, наверное, немного отстаю от жизни.Опять же не критика, а интересно. "Разработчик или тестировщик берутся за документацию не от хорошей жизни и обычно не знают, с чего начать". Простите великодушно, я понимаю, что разраб огромной корпорации огромного проекта может документировать только свой мелкий кусочек работы - ему дали задание, он выполнил и поставил галочку. Но у него тогда все процессы выверены, и если ему придет задача "напиши инструкцию", то с ней должен прийти и шаблон, а проверяющий техпис все равно вычитает, отредактирует и поправит. Иначе его кусочек ни в общую документацию не уложится, ни проверку качества не пройдет - потому что "чукча читатель, а не техписатель". Но у вас вроде бы пример другого кейса, где команда маленькая, и каждый поневоле "и швец и жнец". Но в такой команде каждый, напрямую, фактически имеет доступ ко всей документации, мало того - она никак не создается без общей кооперации! Так что значит "не от хорошей жизни"? Это как раз "хорошая жизнь" микрокоманды - один, например, совмещает обязанности сист.аналитика и шеф-тех.писа, делает структуру документации, прикидывает объем, пишет важные документы вроде ТЗ; джуны-техписы "на подхвате", а остальным перепадает писать те разделы, в которых они разбираются. И даже в такой команде будет и структура документации, и задания. А не бардак и непонятная "личная инициатива". Вот написанная разработчиком инициативно инструкция, она зачем нужна? Ее нет в спецификации документов, которые мы должны дать заказчику. Ее нет в структуре рабочего проекта. Наверное, начинается с "ребят, вам инструкцию написать?", одобрения ведущего доки, месте под нее в структуре проекта (вот эта инструкция привязана к этой версии), шаблона, а не "я принес документ, дайте мне плюсик в карму". Иначе это работа на увеличение энтропии и мусора в доках и "на минусик в карму". Или у вас тот самый кейс "у нас эджайл, нам вообще никакая документация не нужна, пока не приперло, а вот приперло - срочно напишите"? Так там с другого по идее надо начинать, иначе вообще все похороните в авгиевых конюшнях...
Простите, без сарказма и критики - немного путаюсь в ваших терминах "документация" и "статья" и не немного понимаю, вы про документацию или про некий контент, который хотите где-то опубликовать (на Хабре, на сайте компании, в личном блоге) или кому-то дать почитать?
Опять же не как критика. По моему некоторому опыту, все же первое, с чего следует начинать - это "целевая аудитория". Новому сотруднику компании, потенциальным покупателям продукта и коллегам на выставке нужна совершенно разная информация, о разных вещах, с разными целями, в разном объеме и рассказанная доступным им языком. Смотрите, даже тут на Хабре в каждой статье указывается ключевое - "сложность", время на прочтение и даны теги, кратко характеризующие "о чем". Поэтому сперва надо определиться - кто читатель? Что ему (потенциально) нужно / что вы хотите сообщить и о чем? Для чего и, следовательно, в каком объеме? Эти ответы сразу определят вид "документации". Это краткая инструкция или полное руководство? Это рекламный проспект или статья для коллег-спецов? Вид определяет форму, структуру, подачу материала. Человечество пишет уже тысячи лет, так что вам не придется изобретать велосипед. Вам нужно красиво расписать достоинства товара? Вам к маркетологам и рекламщикам в стыке с психологами и дизайнерами, с соответствующим запросом (условному гуглу)"как написать рекламный буклет, чтобы он понравился" или условному промпту ЛЛМке "рекламный буклет для такого-то товара для мужика 30-40 лет такого-то уровня дохода, в таком-то стиле, чтобы привлечь внимание к товару / создать положительное впечатление..." и т.п.. Использование лит.приемов и игры слов здесь не баг, а фича! Вы работайте с гоской, или, о ужас, внезапно с военкой? Вам нужен тамошний канцлярит и стандарты (например ЕСПД), и тщательная выверка вплоть до запятых - иначе вас не воспримут всерьез. И, да, это тавтологии и применение слов, принятых "по стандарту", а не "как все называют", даже если это звучит буквально допотопно. У вас новый сотрудник - студент, который первый раз такое вижу" или крутой спец "дайте покопаться под капотом"? Им нужен разный объем информации и в разном изложении. У вас "спец в поле" - как было тут в комментах выше? Такому спецу нужна инструкция, которую удобно загнать прямо в смартфон, где все по шагам с маркерами, а идеально - с иллюстрациями или "примечаниями" по ссылкам прямо в "шаге": понадобилось, ткнул ссылку, посмотрел, вернулся. Здесь условия использования определяют форму, форма - изложение контента. Никаких длинных фраз. Никаких пространных уточнений - их при необходимости в примечания.
Да, я помню, что статья "для самых маленьких", а я пугаю "маркетологами" и страшным словом "ЕСПД". Но давайте сразу определим правильное направление, "куда лежать". "У нас Эджайл, нам продукт важнее документирования!" - ровно до тех пор, пока у вас один из команды не уволился. Или, тьфу-тьфу, не заболел или не произошел несчастный случай (всякое бывает). Потому для вас все начинается с "сколько необходимо и достаточно, чтобы новый сотрудник быстро вошел в курс дела", а не был вынужден "расшифровывать легаси". Не "мы продвинутые и напишем красиво и молодежно (понятно нам), мы что, динозавры?!" - а "зубодробительно и в стиле аж 70х, но понятно и приятно госке". Тогда вам не придется переделывать, теряя в репутации ("ох уж эти школяры-вайтишники!") - уже скачанный из инета шаблон сразу идет вам в плюсик, а стиль ЛЛМка при необходимости выправит. И пара местных хабровских статей маркетологов (а то и древних книжек "по рекламе") вам для "рекламного буклета" поможет больше, чем попытка "в лоб" использовать жи-пи-чат: на нейронки и их "натворения" у всех скоро будет "баннерная слепота".
Спасибо за статью, в целом мысль правильная и картинки очень милые!
Всем удачи в написании вашей документации! :))))
А какое отношение Макс имеет к полосам?
Я вот с сабами смотрю, чтобы слышать оригинальную озвучку, так когда саб на "черной полосе", а не на картинке - это прям отлично! И кадр тоже предпочитаю видеть "как задумал автор" - вам может что-то и "лишнее", а мне детали рассматривать бывает интересно, интерьер, пейзажи. Вы, например, знаете, что англичанин, посмотревший нашего "Холмса", говорил про детали интерьера: "такие же штуки были у моей бабушки"?
Так мне к умным или к красивым? ;)
Пожалуй, уточню следующие вещи.
1) Кофе и чай - это не чистые аптечные таблетки, где точно указана доза кофеина, это "экстракт" из растительного сырья, полученный "кустарным" способом. Смесь сложных химических веществ, которую вы получаете в чашке, может разительно отличаться в зависимости от вида и качества сырья (индийский массмаркетный зеленый чай в пакетиках и какой-нибудь приличный рассыпной китайский, как и дешевая массмаркетная робуста и приличная арабика - это совершенно разные вещи не только по вкусу, но и по тому же содержанию кофеина), от способа приготовления (заваренный кипятком "чифирь" против китайского пролива, растянутого на час, фильтр-кофе против эспрессо... промолчу про ристретто) и даже от качества и температуры воды (поговорите как-нибудь с хорошим чайным мастером в китайской чайной, узнаете много удивительного). Эффект даже от кофе из двух пачек одной цены разных фирм из ближайшего магазина, или "чистого" американо и точно такого же с молоком может быть разным, с чаем бывает еще сложней. Хотите попробовать усилить эффект от чая или кофе? Не обязательно добавлять больше: используйте "более тонкий помол" (кофе "для кружки" с помолом "в пыль"), заварите почти кипятком (в обычных условиях зеленый чай все же принято заваривать горячей водой, а кофе "в турке" - не кипятить) или используйте "жесткую" воду (можно просто добавить чуть соли) - это усилит экстракцию, но скажется на вкусе. Хотите смягчить и растянуть эффект? Добавьте молоко или сливки.
2) На полученную сложную химическую смесь у каждого человека индивидуальная реакция. Кто-то от кофе (или китайского шу пуэра) просыпается, кто-то, напротив, засыпает; кому-то зеленый чай вообще как "вода" с нулем эффекта. Какой эффект получите от конкретного напитка лично вы - узнать только опытным путем :) Но соблюдайте ТБ любого эксперимента. Есть гипотоники, есть гипертоники, есть язвенники. Никакой новый напиток желательно не пробовать натощак. Если у вас явные проблемы с АД - перед "а попробую-ка я ристретто из этой дешевенькой робусты" (или "вот этот элитный китайский чай") запаситесь тонометром и лекарством: в чашке может отказаться не "безопасная ароматизированно-подкрашенная водичка", а нечто с такой ядреной (индивидуально для вас) концентрацией, что буквально на глазах (по бегущим циферкам на браслете тонометра) словите криз. А если "чай с добавками для бодрости", а вы аллергик - антигистаминным, и пробуйте малыми дозами, аккуратно.
/зануда мод он Не спецификация, а обязательный документ по ГОСТ, "текст программы".