Как стать автором
Обновить
-17.31

Подготовка технической документации *

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга
Уровень сложности

Как техпису изложить фактуру в техдоке?

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров3.5K

Ни в форумах, ни в блогах, ни в России, ни в англоязычных ресурсах я не смог найти информацию о том, как логично упаковать всю релевантную фактуру в приятный технический документ. В книге М. Ильяхова «Пиши, сокращай» есть отдельная глава про дидактику, но там очень мало, вскользь и не совсем о том.

Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.

Читать далее
Всего голосов 7: ↑5 и ↓2+3
Комментарии2

Почему UserStory и ныне там?

Уровень сложностиПростой
Время на прочтение8 мин
Количество просмотров6K

Когда в коллегах согласья нет,
На лад проект их не пойдет,
И выйдет из него не profit, только cost.

Однажды Бэкендер, Фронтендер да Аналитик
Везти с тасками US взялись,
И вместе трое все в него впряглись;

Из кожи лезут вон, а US всё нет ходу!
Таски для них казались и легки:
Да Фронт рвется в Cloud-решения,
Бэк пятится назад, а Аналитик тянет в воду.

Кто виноват из них, кто прав, - судить не нам;
Да только UserStory и ныне там.

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

Го дальше!
Всего голосов 7: ↑5 и ↓2+3
Комментарии22

Почему мы ошибаемся при первоначальной оценке фич?

Уровень сложностиПростой
Время на прочтение8 мин
Количество просмотров8.8K

Так бывает, что в проектах, в которых я участвую, первоначальная оценка разработки проекта расходится с реальными сроками. И кажется, что уже всё сделали: внедрили скрам, планирование, ежедневные летучки, грумминг, внутри команды наладили коммуникацию, но всё равно раз за разом сроки разработки отодвигаются

И возникает закономерный вопрос — да что не так-то?

Читать далее
Всего голосов 26: ↑24 и ↓2+22
Комментарии35

Docs as Code для художественной литературы. Делаем творческий сайт ребенка с помощью MkDocs

Уровень сложностиПростой
Время на прочтение13 мин
Количество просмотров7.4K


Docs as Сode — подход к работе с текстами, подразумевающий написание текста как кода:


  • в простом текстовом редакторе или IDE;
  • с использованием системы контроля версий;
  • с CI / CD / Code Review.

В настоящее время Docs as Code широко применяется при работе с технической документацией, давая техническим писателям и проектным командам массу удобств и преимуществ.


Но что если пойти дальше, попробовать такой подход не с техническими, а с художественными текстами? Что если автор — не технарь и не айтишник? Просто юный начинающий писатель, который пробует писать прозу и стихи ручкой на бумаге, и надеется познакомить широкую публику со своим творчеством?


В этой статье я расскажу о таком эксперименте (забегая вперед, удачном). Моей дочери 11 лет, она пишет сказки, стихи и рассказы. Чтобы поддержать ее увлечение, я помог ей создать литературный сайт, используя подход Docs as Code. Она успешно освоила основы Markdown и Git. Сейчас она самостоятельно публикует новые произведения и обновляет новости на своем сайте https://lib-beliakova.github.io/.

Читать дальше →
Всего голосов 44: ↑44 и ↓0+44
Комментарии17

Истории

Заблуждения об именах в документах

Уровень сложностиПростой
Время на прочтение6 мин
Количество просмотров12K

Умный дядя по имени Дейл Карнеги писал, что имя человека - самый сладостный и самый важный для него звук на любом языке. Соответственно, лучший способ обидеть пользователя – исказить его имя в базе или не принять вводимое значение.

Присвоение и изменение имени/фамилии/отчества в каждой стране регулируются Семейными Кодексами и соответствующими Законами. При этом законодательные акты не предусматривают exceptons, которые могут произойти в реальной жизни. А рядовые аналитики и программисты не всегда готовы читать сотни страниц канцелярита, чтобы узнать требования к полям в базе и формах. Дабы случайно зарегистрировавшийся Аполлинарий Воскобойников не обрушил старательно разработанную систему, добро пожаловать под кат.

Читать далее
Всего голосов 22: ↑22 и ↓0+22
Комментарии77

«База знаний — не самурай». 7+ ключевых советов про БЗ от техписов и не только

Время на прочтение3 мин
Количество просмотров4.2K
В феврале мы в «Лаборатории Касперского» провели большой митап «База знаний здорового техписа». Пятеро наших коллег из разных компаний, которые занимаются менеджментом знаний и руководят работой с технической документацией и веб-контентом, рассказали о том, как у них это устроено.



Здесь в посте — краткая выжимка эфира в семи ключевых тезисах. Если же вам интересно послушать более развернутую дискуссию и аргументы участников, посмотрите запись митапа здесь или в виджете ниже. А еще можно свободно пообщаться с участниками эфира в этом чате.
Читать дальше →
Всего голосов 9: ↑8 и ↓1+7
Комментарии0

Распознавание корпоративных документов: как не утонуть в море бумаг?

Время на прочтение7 мин
Количество просмотров2.7K

Мы подсчитали, что ручной ввод данных из типовых форм занимает 6–7 часов в день. Автономная система Smart Document Engine на смартфоне справляется с подобной задачей буквально за минуты. В этой статье мы расскажем о самых эффективных бизнес‑кейсах применения нашей мобильной OCR.

Читать далее
Всего голосов 2: ↑2 и ↓0+2
Комментарии10

Как Heflo поломал мою картину мира

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров3.3K

Привет, Хабр! Меня зовут Георгий Ржавин, работаю процессным архитектором в компании GlowByte, руковожу направлением Business Process Management. В этой статье хотел бы поделиться моим видением мирового рынка ПО (в первую очередь доступного в России) по моделированию и автоматизации процессов, а также рассказать о новых инструментах. Прежде всего материал будет интересен для бизнес‑ и процессных аналитиков.

Читать далее
Всего голосов 15: ↑12 и ↓3+9
Комментарии6

5 шагов для устранения «рунглиша» из ИТ-переводов

Уровень сложностиПростой
Время на прочтение6 мин
Количество просмотров7.9K

К моим словам прошу относиться со здоровой долей скепсиса, ибо я не нейтив-спикер, а просто ИТшный переводчик-редактор (пусть даже и с 20-летним опытом).

В последние полгода англо-русские переводы по понятным причинам практически исчезли, и по работе на проверку приходят в основном русско-английские, зачастую на «рунглише». Отмечу, что «рунглишевые» ошибки в присылаемых материалах более или менее однотипные, поэтому я и предположил, что коллегам может быть полезно, если эти ошибки кто-то разложит по полкам.

Эту памятку или «дорожную карту» я опубликовал в своем телеграм-канале несколько месяцев назад, многократно её обкатал на проектах, и убедился в ее применимости — поэтому вешаю ниже.

Шагов в этой памятке 5:

Читать далее
Всего голосов 37: ↑36 и ↓1+35
Комментарии32

Как создать внутреннюю базу знаний для большой IT-компании. Из хаоса в гиперспейсы

Уровень сложностиСредний
Время на прочтение7 мин
Количество просмотров25K

Когда на вопрос «Что за фича?»‎ сказали: «Посмотри в Confluence!»‎

Привет! Меня зовут Таня Дудо, я менеджер продуктовых знаний в Selectel. В тексте расскажу, как решили создать внутреннюю базу знаний о продуктах и процессах для более 800 человек. Опишу, как к этому пришли, кропотливо выуживали важную доку из массива данных и придумали решение — гиперспейсы.

Мы развиваем базу знаний на Confluence, но подходы и решения, описанные в тексте, могут быть полезны в работе с другими площадками. Мемы и уроки из опыта — под катом.
Читать дальше →
Всего голосов 73: ↑71 и ↓2+69
Комментарии15

Почему каждый второй из наших прототипов для новых проектов уходит в стол, а не в продакшен?

Время на прочтение3 мин
Количество просмотров2.4K

Короткий ответ: потому что когда заказчики по прототипу получают оценку у разработчиков, они понимают, что не потянут разработку по деньгам.

Рассказ веду от лица основателя Проектората — бренда, объединившего самостоятельных проектировщиков/UX-дизайнеров.

Речь идёт исключительно о новых проектах, а не доработках в существующие. Самый распространённый сценарий выглядит так. Человек придумывает идею для своего продукта и решает его разработать. Он ищет по знакомым контакты программиста. Находит и в двух словах объясняет ему задачу. Программист тыкает пальцем в небо и называет стоимость разработки. Допустим, два миллиона. И намекает, что оценка примерная и было бы неплохо посмотреть на техническое задание.

Читать далее
Всего голосов 10: ↑10 и ↓0+10
Комментарии10

Приглашаем на онлайновый митап про базу знаний «здорового техписа»

Время на прочтение1 мин
Количество просмотров1.3K
В среду, 15 февраля, в 15 часов (МСК) мы проведем онлайновый митап под названием «Kaspersky Tech: База знаний здорового техписа».

На митапе выступят пять спикеров, которые в своих компаниях занимаются менеджментом знаний и руководят работой с технической документацией и веб-контентом. Темы их выступлений всесторонне охватят область Баз знаний (БЗ) – от процесса создания БЗ и ее «продажи» остальным командам внутри компании, до поддержки БЗ и измерения ее эффективности. А также, конечно, поговорим, как грамотно внедрить использование Базы знаний в пайплайн разработки.


Читать дальше →
Всего голосов 9: ↑8 и ↓1+7
Комментарии1

Арт-терапия и вялотекущая миграция с монолита

Уровень сложностиСредний
Время на прочтение7 мин
Количество просмотров2.3K

Когда я пришла на новый проект, мне сказали, что миграция пройдёт в ближайшее время, и мне осталось «лишь» разобраться ней: огромная инфраструктура, множество систем и интеграций между ними, разнородные пользователи всевозможных масштабов с разными требованиями, целевые стратегии, бизнес задачи, множество команд развития и не одна линия поддержки, требования учета изменений законодательства и соблюдения стандартов безопасности, современные технологии, стремительное изменение мировой ситуации. Это всё, что меня окружает, и в чём надо разобраться.

При этом сложно понять структуру, найти какой-то единый документ, где можно было бы увидеть схему, как она есть сейчас и как это будет. Ввиду нехватки информации и сложности задачи, возникает ощущение безысходности и невозможности оценить верность решения с точки зрения проектируемой системы. Проект нужно начать делать сейчас, и находить способы распутывания текущего положения

Иногда казалось, что система очень хочет жить и намеренно меня запутывает. Моё стремление понять, с чем я имею дело и как это понять и подсветить какие-то подводные камни, риски, привело меня в замешательство, где я ни черта не понимаю, что происходит. Сложная задача требует нестандартных решений, и здесь возникает арт-терапия.

Читать далее
Всего голосов 19: ↑19 и ↓0+19
Комментарии7

Ближайшие события

Поздравить пользователя 00 февраля с минус семитысячелетием или Заблуждения о паспортах в базе

Время на прочтение6 мин
Количество просмотров6.3K

Времена, когда «усы, лапы и хвост» достаточно хорошо удостоверяли личность любых двуногих и четвероногих миновали. Времена, когда достаточно показать «мультипасс» ещё не наступили.
И пока мы ждём светлого будущего, постараюсь развеять некоторые заблуждения разработчиков и пользователей о хранении паспортов в базе.

Мифы и легенды про документы
Всего голосов 29: ↑28 и ↓1+27
Комментарии48

На старт, внимание, патч! Как реализовать онлайн-документацию для накопительных изменений

Время на прочтение5 мин
Количество просмотров1.2K

Привет читателям! Меня зовут Владимир Маркиев, но сегодня зовите меня Александр Сергеевич, я — технический писатель в компании, которую нельзя называть. Когда компания, которую нельзя называть, создавала онлайн-документацию при помощи Antora, стояла задача оставить место, куда в будущем интегрируется список накопительных изменений.

Читать далее
Всего голосов 1: ↑0 и ↓1-1
Комментарии2

7 шагов по организации пространства в серверной стойке

Время на прочтение13 мин
Количество просмотров33K

В этой статье мы говорим о грамотном размещении оборудования в стойке, а иными словами, системно рассматриваем эксплуатацию серверного шкафа: от составления плана и инсталляции до маркировки проводов. Всё повествование строится, в первую очередь, на моем опыте работы инженером ЦОД, и, хорошо это или не очень, я стараюсь придерживаться именно этих правил и практик.

Читать далее
Всего голосов 8: ↑8 и ↓0+8
Комментарии13

Как писать конспекты на компьютере быстрее, чем от руки, при помощи VS Code

Время на прочтение5 мин
Количество просмотров47K

Привет всем!

В этой статье говорится о том, как я конспектирую на компьютере, а точнее описываются способы ускорения набора LaTeX-овского текста.

Читать далее
Всего голосов 42: ↑42 и ↓0+42
Комментарии50

Декларативное построение диаграмм

Время на прочтение2 мин
Количество просмотров6.1K

Код может быть красивым сам по себе, но графическое представление не помешает.

Диаграммы, СТАНОВИСЬ!
Всего голосов 25: ↑24 и ↓1+23
Комментарии19

«И швец и жнец» или обзор полезных расширений для XWiki

Время на прочтение4 мин
Количество просмотров5K

 

Вот уже второй год, как мы используем XWiki, вместо Confluence. 

За это время я к ней привык и даже в некотором роде полюбил. Поэтому не могу пройти мимо такого важного события как выход новой LTS версии 4.10.X.

Если вы не знакомы с релизным циклом XWiki, то вас может удивить, что LTS версия выходит в конце года и в течение всего следующего года получает обновления. Иногда бывает так, что обновления версии XWiki, что-то правит и одновременно что-то ломает, но в целом как обновление того стоит. Например, в 14 версии неплохо улучшили работу с вложениями, экспортом PDF и диалогом вставки изображений в редакторе.

Сегодня я не буду вдаваться в технические подробности, а просто сделаю беглый обзор функционала, рассчитанный в первую очередь на людей только что узнавших об XWiki. Обозревать мы будем самую последнюю на текущий момент версию 14.10.2 со Standard Flavor, установленную через Docker образ.

Читать далее
Всего голосов 7: ↑6 и ↓1+5
Комментарии3

DocOps на Flow 2022

Время на прочтение4 мин
Количество просмотров3.2K


29-30 ноября прошла конференция для аналитиков FlowConf 2022. Основная особенность конференции — ее ориентация на конкретные практические рецепты. Одним из направлений, которое содержит много таких рецептов, стал Docs As Code или, в более широком смысле, DocOps в работе аналитика. В посте представляю обзор этого направления.

Читать дальше →
Всего голосов 19: ↑19 и ↓0+19
Комментарии1