Гостопедия

Смущать, да. Смешно получилось. Давайте так на это посмотрим. На уровне текстового процессора или языка разметки таблица — это всего лишь техническое решение, которое позволяет определенным образом расположить материал на странице. Мы можем использовать это решение по-разному и с разными целями. Если мы публикуем данные, не знаю какие, таблицу калорийности продуктов, допустим, то данные в ячейках действительно должны быть атомарными. Кабачок столько-то калорий, а сгущенка столько-то. Но могут быть и другие задачи, связанные, скорее, с версткой, чем с публиукацией данных. Например, мы хотим описать роли пользователей, указав для каждой роли перечень решаемых задач. Собрать роли в таблицу — вполне естественная идея. Организовать задачи в списки — тоже вполне естественное решение. Лишь бы строки таблицы оставались обозримыми. |---------|-------------------------------| | Роль | Задачи | |---------|-------------------------------| | Повар | - Составление меню | | | - Приготовление еды | |---------|-------------------------------| | Дворник | - Уборка территории | | | - Изгнание чужаков с парковки | |---------|-------------------------------| Что в этом такого уж плохого? А если такая таблица недопустима, то как надо было бы расположить такой материал? Отказаться от таблицы вообще, писать абзацы кирпичами? Таблицу оставить, но отказаться от списков, писать задачи через запятую? Оба решения ухудшили бы обозримость материала для читателя.

Возник неожиданно интенсивный спор о том, хороши ли списки в таблицах, или это они нечисты ритуально. Не буду его перепощивать сюда весь, можно по кликнуть по этому сообщению и посмотреть весь тред. https://t.me/TechDocIT/18032

Что же, придется обсуждать списки в таблицах. Напишу про них позже.

Как вы думаете, когда написан этот текст? Машины «приобщаются» в наши дни к творческой деятельности не менее интенсивно, чем люди. Беря на себя человеческие функции сначала в нетворческих, вспомогательных областях, они шаг зашагом проникают и в святая святых творчества, которая еще совсем недавно считалась вечной прерогативой человеческого духа. Машины начинают «создавать небывалое» прежде всего в точных и естественных науках, но все шире также и в гуманитарных дисциплинах; они проникают в неизведанные области знания и безжалостно вскрывают неточности и противоречия в общепризнанных положениях.

Говорите ли вы по-графически? Сегодня широко известны примерно 150 графических языков и нотаций, не считая нишевых, а также одноразовых, которые авторы сами придумывают по ходу дела. Более или менее популярных инструментов для работы с такой графикой сейчас около 200. Но сделать удачную иллюстрацию, схему или диаграмму не так просто. Во-первых, это разные жанры, требующие особого подхода. Схема может быть обширной и сложной, но предполагает строгое следование выбранной нотации. Диаграмма должна быть обозримой: в идеале читатель схватывает ее одним взглядом. Иллюстрация передает мысль образами, для этого она должна использовать понятные аудитории штампы. Во-вторых, владения нотациями и рисовалками недостаточно. Нужно как таковое умение изъясняться графическим языком, что-то вроде графической риторики или композиции. Пренебрегая этой стороной дела, авторы наполняют технические документы некрасивыми и непонятными картинками, ворующими у читателей время. Как рисовать понятно? Об этом поговорим на курсе Documentat, который пройдет 18–20 августа.

Дорогие коллеги, скажите, как вы думаете, нужен ли в курсе по Docs as Code модуль про то, как публиковать из Markdown в PDF с заданным (в том числе, гостовским) оформлением? Или это разные части жизни, они редко пересекаются?

(Желаю всем продуктивной рабочей недели... ) Песенка худшей версии Познакомьтесь, друзья, Это завтрашний я, Идеальный завтрашний я! До восьми он читал, До обеда лутал, Дальше отдых, спорт и семья, Он совсем не обжора, Для него тренажера Груз отрадней вкуса котлет, Не сутулый очкарь, Не занудный сухарь, А веселый прямой атлет, Но сегодня, друзья, Ваш сегодняшний я Смотрит ленту четвертый час, Сто постов пролистал, Словно грузчик устал, И попкорна извел запас, Он в иные моменты Оставляет комменты, Или вдруг впадает в тоску, Вам наверно знакомо Это вечное фомо, Злое чувство дыры в боку... Темнота в небесах, Ноль всего на часах, Стало завтра нынешним днем, Продуктивный двойник В новом завтра возник, Не печальтесь, друзья, о нем, Вдруг он страшный нахал, И на всех он чихал, Что отмочит еще, бог весть, Я дурак-дураком, Но давно вам знаком И понятен, какой ни есть.

Уроки вайбкодинга 1. Сделай правильный выбор Будь занудой — начни с маркетинга. Раньше узким местом были возможности, но в мире, где все могут всё, ключевым становится выбор правильной темы. Не действуй по накатанной, если ты не корпорация, не верь своим гипотезам, если ты не гений. 2. Твой код не твой Программирование больше не творчество. Сложно это принять, если последние лет пятнадцать холиварил об именах переменных, паттернах проектирования и чистоте кода. Отпусти свой код, роман с ним закончен. 3. Не всё коту масленица Чёрт знает, на чём споткнется агент. Банальное вроде бы требование вдруг становится страшным препятствием. Как вы поступите, если агент перестанет справляться с тем или с этим? Заранее продумайте обходные пути, и как вы поймете, что настало их время. 4. Прекращай вовремя Агенты способны проявлять нелояльность, саботируя ваши приказы, сколько их ни тверди. Важно распознать эту ситуацию вовремя и не уйти в дофаминовую петлю, как это бывает с игроманами. Действуйте радикально: меняйте требования или предлагайте рабочую реализацию сами. 5. Знай своё незнание Вайбкодер действует в трёх зонах: что он мог бы сделать сам, что мог бы сделать в принципе, и на что не способен вообще. Замыкаться в двух первых — чрезмерное ограничение, вторжение в третью — риск утратить контроль над проектом. Приходится отдавать себе отчёт, в какой зоне ты находишься сейчас, и управлять рисками, пока они сами не управляют тобой. 6. Спасительная документация Чат к делу не пришьёшь. Если серия правок завела проект в дебри, то лучшим выходом может стать его рефакторинг строго по требованиям. Поэтому любое указание агенту нужно сначала вносить в спецификацию. После каждого важного шага вперёд велите агенту задокументировать полученную реализацию, тогда вынужденное отступление (а оно неизбежно) обойдётся дешевле. 7. Нужно только внимание Не то, с которого всё началось. В мире вайбкодинга способность создать рабочую систему сама по себе стоит недорого. Главное, чтобы целевая аудитория заметила ваш проект. Будь занудой — начни с маркетинга.

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

Курс по скриптам автоматизации. 16-18 июня. В чем вообще смысл, о чем пойдет разговор. Раньше, чтобы писать скрипты и автоматизировать свою работу, тебе нужно было уметь программировать. Там не высший класс программирования, но это примерно как вязать, или ты умеешь, или нет. Я не умею вязать, поэтому я даже шарф не свяжу. Сейчас ситуация поменялась. Есть разные ИИ, поэтому в принципе, чтобы писать скрипты автоматизации, тебе не нужно уметь программировать, а нужно уметь ставить задачи. На техписовской улице грузовик с карамельками перевернулся. Но все же необходимо понимать, что и какими средствами ты делаешь, как эти средства устроены, что они могут, как себя ведут. Курс будет об этом. Что конкретно будем обсуждать: - сборочные скрипты, работающие в логике целей (make, Ant); - автоматизация оформления документов: XSLT, FO; - офисная автоматизация (MS, Libra), VBA; - командные файлы ОС, как без них жить, никак.

https://www.youtube.com/watch?v=AzpdvGMAqJY

Приходите сегодня на митап!

Привет, коллеги! Кинцо посмотрите. Потом объясню, что это, и зачем. https://www.youtube.com/watch?v=KyhreT7kyYg

Единый источник и DITA: в чем ее особенность? (Часть 3) На рисунке два верхние ряда — информационные типы DITA "из коробки", а нижний — специализированные информационные типы, которые мы могли бы сделать для руководства по эксплуатации трактора.

Единый источник и DITA: в чем ее особенность? (Часть 2) Хорошо, а с топиками что? Предъявлены ли к ним какие-нибудь требования кроме краткости и самодостаточности? Зависит от инструмента и подхода. Многие средства разработки позволяют авторам писать топики как угодно, но так называемый компонентный подход, реализованный в DITA, требует от них дисциплины. Каждый топик должен быть отнесен к определенному информационному типу. Информационный тип определяет характер содержания топика и его роль в документе. Например, у нас могут быть топики-концепции, содержащие всякие теоретические введения, топики-задачи, содержащие указания пользователю, и справочные топики с дополнительной информацией. Технически принадлежность топика к определенному информационному типу выражена его внутренней структурой. Скажем, топик-задача должен содержать последовательность шагов, а каждый шаг должен состоять из описания действий пользователя, реакции системы и полученного результата. Таким образом реализуется универсальный принцип: подобное описывают подобно. Несколько авторов могут договориться между собой о соблюдении конкретных информационных типов, или начальник может этого от них потребовать. Дальше успех будет зависеть от внимательности и дисциплины этих людей. DITA позволяет реализовать информационные типы технически, то есть, навязать авторам информационные типы через XML-редактор, например Oxygen или XMLmind. DITA не только предлагает стандарт структурирования топиков в зависимости от их назначения, но и воплощает его в инструментах. А что, если нам нужно расширить этот стандарт для нужд нашего проекта? Так DITA для этого и придумана. Вернемся к примеру с трактором. Предположим, что в руководстве по эксплуатации нам нужны разные типы процедур: по управлению трактором, по техническому обслуживанию, по ремонту и по решению проблем во время работы. Тогда мы можем специализировать стандартную дитовскую процедуру, «отрастив» от нее новые информационные типы. В каждый тип мы добавим необходимые рубрики, исключим лишние, сделаем какие-нибудь особые типы шагов и т. п. Важно, что это будет не просто система внутренних договоренностей, но еще и система настроек, которая обеспечит полноценную поддержку этих информационных типов в редакторах и в средствах публикации. Продолжение

Единый источник и DITA: в чем ее особенность? (Часть 1) В предыдущем (не в последнем, заметьте!) посте я рассказал, что единый источник — это технология, которая позволяет составлять разные документы и небольших фрагментов. Предполагается, что эти фрагменты невелики по объему и более или менее независимы друг от друга по содержанию. Обычно такие фрагменты называют топиками. Разбив контент документации на топики, мы получаем что-то вроде конструктора. Чтобы сделать нужный документ, мы выбираем из этого конструктора подходящие топики и соединяем и соединяем их в структуру, которая определяется жанром документа. Также предполагается, что мы формируем документы не вручную, а с помощью какой-то системы, состоящий из скриптов, стилей и прочей автоматизационной утвари. Продолжение

Так о чем был наш крайний митап? О гостах же. Проблема со словом последний (last) есть и в английском языке, по крайней мере, ее видят авторы руководства по стилю журнала Economist. Не вижу оснований не доверять сотрудникам уважаемого издания. Они рекомендуют заменять его словом предыдущий (previous) в контекстах, где слово последний способно породить печальную двусмысленность. Или, наоборот, оптимистичную: плохие вещи тоже ведь могут случаться в последний раз. Будем помнить об этом и надеяться на лучшее.

14 мая проведём митап про Docs-as-Code и единый источник Вы думали, что Docs-as-Code и методология единого источника — это одно и то же? А вот и нет! Поговорим об этом ровно через две недели на митапе «Docs-as-Code и единый источник: преимущества, слабости, перспективы». Вас ждут три доклада о Docs-as-Code, методологии единого источника и технологии DITA: 🔹 Михаил Острогорский, Гостопедия Docs-as-Code и единый источник — одно и то же или совсем разное? 🔹Василий Лукьянов, технический писатель, Documentat Может ли Docs-as-Code сделать вас умнее и богаче? 🔹Анна Второва, технический писатель, Т1 DITA в крупном проекте — оправдала ли она себя? 📅 Когда: 14 мая в 17:00 по МСК 📍 Где: на YouTube, Rutube и в VK Видео