Комментарии 14
Очень крутая и полезная статья🔥👍
Не пробовали такой сценарий для не умеющих писать складные тексты? Напишите всё-всё, что знаете о своем продукте свои корявым языком, можно тезисно. Подключите к описанию все-все документы, которые есть от разработчиков и других участников проекта. Загрузите весь этот большой текст в нейросеть и закажите у нее на основании загруженного текста инструкции, руководства, white paper, статью для онбординга... Проверьте каждый полученный документ на смысл и факты.
Сам я никогда таким подходом не пользовался, потому что сам писать умею. То есть, свой текст я никогда не загружал в неросеть для литературной обработки. Наоборот, если заказывал какую-то справку по неизвестной мне теме, то перепроверял факты и обрабатывал литературно.
Я не сталкивалась с командами, которые пробовали бы такой подход и предпочитаю писать тексты самостоятельно с самого начала, потому что могу, умею, практику.
Часто в попытке сэкономить время и сократить трудозатраты, можно наоборот потратить еще больше и первого, и второго. Если не обработать предварительно текст и не подготовить развернутый промпт, а закинуть всё, что есть по проекту, почти полностью заполнив контекстное окно, то с высокой долей вероятности нейросеть выдаст ерунду, но с очень убедительной подачей. И получится, что нужно: сначала подготовить промпт для нейросетки, потом проверить результат и исправить ошибки. Проще сделать самому. Тема, на самом деле, холиварная и интересная. Возможно, послужит основой для одной из следующих статей.
Я, например, имея инструкцию на 400 страниц, сделал инструкцию типа "быстрый старт" на 19 страниц. Просто описал то, что инженер реально делает с банкоматом при его установке.
А вот как задать эту работу ИИ, если он ничего не знает о порядке работы сотрудника и о том, какие настройки следует изменить именно для моего банка?
Вы молодец! ))
А у меня статья про ведение документации уже четвертый день висит в песочнице 😅
Простите, без сарказма и критики - немного путаюсь в ваших терминах "документация" и "статья" и не немного понимаю, вы про документацию или про некий контент, который хотите где-то опубликовать (на Хабре, на сайте компании, в личном блоге) или кому-то дать почитать?
Опять же не как критика. По моему некоторому опыту, все же первое, с чего следует начинать - это "целевая аудитория". Новому сотруднику компании, потенциальным покупателям продукта и коллегам на выставке нужна совершенно разная информация, о разных вещах, с разными целями, в разном объеме и рассказанная доступным им языком. Смотрите, даже тут на Хабре в каждой статье указывается ключевое - "сложность", время на прочтение и даны теги, кратко характеризующие "о чем". Поэтому сперва надо определиться - кто читатель? Что ему (потенциально) нужно / что вы хотите сообщить и о чем? Для чего и, следовательно, в каком объеме? Эти ответы сразу определят вид "документации". Это краткая инструкция или полное руководство? Это рекламный проспект или статья для коллег-спецов? Вид определяет форму, структуру, подачу материала. Человечество пишет уже тысячи лет, так что вам не придется изобретать велосипед. Вам нужно красиво расписать достоинства товара? Вам к маркетологам и рекламщикам в стыке с психологами и дизайнерами, с соответствующим запросом (условному гуглу)"как написать рекламный буклет, чтобы он понравился" или условному промпту ЛЛМке "рекламный буклет для такого-то товара для мужика 30-40 лет такого-то уровня дохода, в таком-то стиле, чтобы привлечь внимание к товару / создать положительное впечатление..." и т.п.. Использование лит.приемов и игры слов здесь не баг, а фича! Вы работайте с гоской, или, о ужас, внезапно с военкой? Вам нужен тамошний канцлярит и стандарты (например ЕСПД), и тщательная выверка вплоть до запятых - иначе вас не воспримут всерьез. И, да, это тавтологии и применение слов, принятых "по стандарту", а не "как все называют", даже если это звучит буквально допотопно. У вас новый сотрудник - студент, который первый раз такое вижу" или крутой спец "дайте покопаться под капотом"? Им нужен разный объем информации и в разном изложении. У вас "спец в поле" - как было тут в комментах выше? Такому спецу нужна инструкция, которую удобно загнать прямо в смартфон, где все по шагам с маркерами, а идеально - с иллюстрациями или "примечаниями" по ссылкам прямо в "шаге": понадобилось, ткнул ссылку, посмотрел, вернулся. Здесь условия использования определяют форму, форма - изложение контента. Никаких длинных фраз. Никаких пространных уточнений - их при необходимости в примечания.
Да, я помню, что статья "для самых маленьких", а я пугаю "маркетологами" и страшным словом "ЕСПД". Но давайте сразу определим правильное направление, "куда лежать". "У нас Эджайл, нам продукт важнее документирования!" - ровно до тех пор, пока у вас один из команды не уволился. Или, тьфу-тьфу, не заболел или не произошел несчастный случай (всякое бывает). Потому для вас все начинается с "сколько необходимо и достаточно, чтобы новый сотрудник быстро вошел в курс дела", а не был вынужден "расшифровывать легаси". Не "мы продвинутые и напишем красиво и молодежно (понятно нам), мы что, динозавры?!" - а "зубодробительно и в стиле аж 70х, но понятно и приятно госке". Тогда вам не придется переделывать, теряя в репутации ("ох уж эти школяры-вайтишники!") - уже скачанный из инета шаблон сразу идет вам в плюсик, а стиль ЛЛМка при необходимости выправит. И пара местных хабровских статей маркетологов (а то и древних книжек "по рекламе") вам для "рекламного буклета" поможет больше, чем попытка "в лоб" использовать жи-пи-чат: на нейронки и их "натворения" у всех скоро будет "баннерная слепота".
Спасибо за статью, в целом мысль правильная и картинки очень милые!
Всем удачи в написании вашей документации! :))))
Благодарю за такой развернутый комментарий!
Про целевую аудиторию Вы совершенно правы. Это действительно важный момент. Обратите внимание, что я начала статью именно с этого – рассказала, кому она будет полезна и для кого предназначена: "тем, кто отчаянно нуждается в документации, но не обладает ресурсами и навыками технического писателя ", я честно говорю о том, что "…не смогу вместить весь свой опыт в одну статью, но точно задам направление и помогу, как минимум, создать черновик документации". Разработчик или тестировщик берутся за документацию не от хорошей жизни и обычно не знают, с чего начать. Поэтому я намеренно использую слова "статья" и "документация" в связке. А именно, употребляю слово "статья" в качестве синонима "единица документации".
Что касается других замечаний, полагаю, это уже следующая ступень – "для опытных". Перегружать информацией: нюансами и тонкостями тех, кто только начинает, не имеет смысла. Спасибо за идею для второй части!
Простите, но у меня написано о ЦА не вашей статьи, а ЦА именно документации, и даже развернуто подробно, почему это важно. Даже ребенка лучше сразу учить правильно, а не "потом поправим". Документация "для коллеги", "для пользователя" и "для (потенциального) заказчика" может вообще называться одинаково, например какое-нибудь "описание программы", но это будут совершенно разные документы, разного объема, структуры и стиля изложения. Потому что, условно, первое - часть рабочего проекта, второе - краткое пояснение пользователю, с чем он работает, а третье - контент для выкладки на сайт.
И... простите, я, наверное, немного отстаю от жизни.Опять же не критика, а интересно. "Разработчик или тестировщик берутся за документацию не от хорошей жизни и обычно не знают, с чего начать". Простите великодушно, я понимаю, что разраб огромной корпорации огромного проекта может документировать только свой мелкий кусочек работы - ему дали задание, он выполнил и поставил галочку. Но у него тогда все процессы выверены, и если ему придет задача "напиши инструкцию", то с ней должен прийти и шаблон, а проверяющий техпис все равно вычитает, отредактирует и поправит. Иначе его кусочек ни в общую документацию не уложится, ни проверку качества не пройдет - потому что "чукча читатель, а не техписатель". Но у вас вроде бы пример другого кейса, где команда маленькая, и каждый поневоле "и швец и жнец". Но в такой команде каждый, напрямую, фактически имеет доступ ко всей документации, мало того - она никак не создается без общей кооперации! Так что значит "не от хорошей жизни"? Это как раз "хорошая жизнь" микрокоманды - один, например, совмещает обязанности сист.аналитика и шеф-тех.писа, делает структуру документации, прикидывает объем, пишет важные документы вроде ТЗ; джуны-техписы "на подхвате", а остальным перепадает писать те разделы, в которых они разбираются. И даже в такой команде будет и структура документации, и задания. А не бардак и непонятная "личная инициатива". Вот написанная разработчиком инициативно инструкция, она зачем нужна? Ее нет в спецификации документов, которые мы должны дать заказчику. Ее нет в структуре рабочего проекта. Наверное, начинается с "ребят, вам инструкцию написать?", одобрения ведущего доки, месте под нее в структуре проекта (вот эта инструкция привязана к этой версии), шаблона, а не "я принес документ, дайте мне плюсик в карму". Иначе это работа на увеличение энтропии и мусора в доках и "на минусик в карму". Или у вас тот самый кейс "у нас эджайл, нам вообще никакая документация не нужна, пока не приперло, а вот приперло - срочно напишите"? Так там с другого по идее надо начинать, иначе вообще все похороните в авгиевых конюшнях...
А в каком формате оптимально составлять документацию, чтобы использовать далее в базе знаний?
Прошу прощения, что вмешиваюсь (я не топик-стартер), но вы не могли бы уточнить, что вы подразумеваете под "форматом" и "базой знаний"? "Формат" - это для вас формат структуры данных конкретного документа или формат структуры (формат ведения) всей документации? "База знаний" - это БД, из которой вы хотите сделать продвинутую аналитическую и статистическую обработку данных, или? Просто автор, как понимаю, тех.писатель, а у вас более технический и очень узкий вопрос. И ответ на него зависит от многих факторов: какая у вас документация, какие объемы данных, где они уже хранятся, что вы собираетесь с ними делать и зачем. Это скорее системно-архитектурный вопрос, а архитектура может быть очень разная. Так что без подробного уточнения вам даже никто не скажет, к кому вам хотя бы примерно с таким вопросом обращаться, чтобы получить релевантный ответ. (Да, я, увы, тоже вряд ли помогу, кроме "распишите подробнее, что вам нужно". Можно попробовать уточнить у бесплатного АИ, что сейчас примерно "покрывает" ваши требования, и тогда тут искать спецов в этой теме и спрашивать. Но с тем же "расширенным вопросом" - "вот у меня есть то и то, хочу то и то, не могли бы вы посоветовать, в каком формате мне лучше делать документацию, чтобы потом можно было". Тут даже лучше не формулировать "оптимально" - с такой точностью вам ответят только за очень большие деньги после тщательного обследования "что у вас").
Предполагаю, если Вы спрашиваете про базу знаний, то документацию пишите для коллег и внешний портал с продающей документацией Вам не нужен. Обращаться к базе будут как разработчики, так и тестировщики, менеджеры, аналитики и другие коллеги, выполняющие разные функции в команде. Я верно предположила? Отталкиваясь от этого предположения, я делаю вывод, что, скорее всего, под базой знаний Вы подразумеваете некий пул статей о проекте, который поможет Вам делиться информацией без лишних созвонов и переговоров, оптимизировать этот процесс, передавать и сохранять знания внутри команды. Как правильно, небольшие компании хранят такую информацию в doc-файлах или корпоративной Wiki, но я считаю этот формат неудобным. Трудно поддерживать актуальность, версионность и решать конфликты при работе одновременно нескольких людей с одним документом. На мой взгляд идеального решения не существует. Но я бы посмотрела в сторону использования систем контроля версий. Например, можно вести базу знаний прямо в Gitlab или Github, в приватном репозитории, рядом с кодом. Читать такую документацию смогут коллеги с разными навыками, у GitLab есть неплохой инструмент для этого, GitLab Pages (а если есть желание и ресурсы, то можно даже настроить выгрузку в ту же Wiki), одним, словом, посмотрите в сторону подхода Docs-as-code.А вот, чтобы поддерживать в таком формате документацию, нужно уметь работать с Git'ом, но это, думаю, для Вас, как для разработчика, не проблема. Всё зависит от ресурсов, целей, уровня, масштабов и навыков команды и Вашего технического писателя.
Подскажите, пожалуйста, верно ли я поняла Ваш вопрос? Ответила ли на него?
Всё просто!
Да! Просто начните писать :) Когда "все постоянно заняты" можно использовать старую добрую "бюрократию" - выделите себе ежедневный слот на "написание чего-нибудь". Например, есть же периоды для походов за кофе, перекуров и общения с коллегами - вот в такие моменты мысли работают лучше всего. Возвращайтесь и фиксируйте.
Пятое. Не бойтесь тавтологии.
Здесь я бы рекомендовал создать глоссарий со всеми возможными синонимами. Повторять термины полезно, но без пересказа работы целого механизма - пусть это будет описано отдельно, вот на это место и ссылаться.
1.Следите за объемом информации. Если ее много, читать вряд ли будут внимательно или полностью. Практика показывает, что длинные тексты мало кому нравится читать.
Информации может быть много, но важнее её подача - форматирование текста. Как минимум, разделять мысли на абзацы и использовать списки.
2.Не распыляйте внимание на детали. Одного-двух предложений будет достаточно.
В формате базы знаний можно вставлять сворачивающиеся инфоблоки.
5.Лучшее решение – порядок слов прямой!
Уж точно не использовать страдательный залог - из текста должно быть понятно кто и что выполняет, система или пользователь (https://habr.com/ru/articles/772022/).
7.Смело добавляйте схемы, картинки и скриншоты для визуализации.
Даже лучше именно с этого и начинать - визуал обычно заходит быстрее текста и дольше запоминается. А еще так намного проще увидеть где чего не хватает.
Документация для самых маленьких