Сейчас нас не очень устраивает качество поиска по сайту, будем решать это во втором квартале. Вероятно, попробуем внешних вендоров поиска.

я вот думал над тем чтобы c помощью
https://github.com/deepset-ai/haystack
и
https://github.com/neuml/codequestion

в внутренним базам данных
но до реализации руки так и не дошли

Принципы knowledge-centered support можно применить в ревью текстов или кода.

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

— Когда вижу в тексте ошибку или место, которое можно легко улучшить, в первую очередь проверяю командную документацию. У нас есть руководство по разметке, совсем небольшой стайлгайд и глоссарий.
— Если нахожу нужное правило или пример «как хорошо», то добавляю ссылку к комментарию.
— Если не нахожу, то сразу пишу дополнение, либо завожу задачу на описание. Все дополнения отдаю команде на ревью.
— Стараюсь формулировать простые правила и давать примеры. Если не получается — значит, мое замечание субъективно или я сам плохо разобрался.
— Внедряю эти принципы в работу всей команды.

Что из этого получается? За последние два месяца командные доки неплохо так приросли и уже экономят время на ревью и передачу знаний. И бóльшую часть текста написал не я.

Конечно, я делал так не всегда. Теперь буду делать осознанно и регулярно.

Скоро мы наймем стажера, а потом ещё штатного техписателя. Тогда наши командные доки и принципы их дополнения пройдут проверку на прочность. Через месяц-другой расскажу вам о результатах.

Короткая заметка шестилетней (март 2015) давности про подготовку спецификаций в разметке org https://katherine.cox-buday.com/blog/2015/03/14/writing-specs-with-org-mode/

спеки…, "Concurrency in Go" был написан в орге

https://usesthis.com/interviews/katherine.cox-buday/

К этому посту у меня есть вопросы, но я забыл их задать. Исправляюсь.

Как у вас устроено ревью кода или текстов? Опираетесь на явные правила или только на личный опыт ревьюера? Как отличаете субъективные и объективные замечания?

Хочу понять, можно ли как-то оптимизировать работу с документами по ГОСТ. Какие инструменты для этого подходят? Кто-нибудь знает видео-блоги на эту тему или текстовые статьи?

Чтоб вот прямо для совсем-совсем чайников расписано было.

Что вы вкладываете в слово "оптимизировать"?
Это не сарказм, я правде не понял

Документов много, они большие - на 50, 70, 100 и более страниц, в них много таблиц, рисунков, схем, повторяющихся блоков текста, зачастую они имеют много версий самих себя. Когда работаешь с тремя и более документами, + тебе присылают правки (которые могут быть в формате редактирования, а могут и не быть) в конце концов путаешься, забываешь, где что исправил и случаются казусы.
При этом надо следить за форматированием, за зоопарком стилей, чтоб у принимающей стороны не дай бог шрифт не изменился или табличка не поехала.
Хочется как-то упростить эту работу.

Принимающей стороне в бумажном виде / ПДФ, тогда ничего не поедет. А версии и правки - 1С, например

Либо Редмайн какой-то

Опять же, я говорю про предприятия, связанные с военкой

В айтишке наверняка есть свои инструменты

+

Вот если б не пояснение про "совсем-совсем" чайников, я бы посоветовал почитать про Foliant, в тему к тому что чат про DocOps

@kvaleev Не помнишь, у кого-то был же шаблон pandoc'а и остальной пайплайн настроенный под ГОСТ?

Ревью перевода помогает обнаружить недостатки оригинального текста.

Мы пишем документацию tarantool.io на английском, а потом переводим на русский. Раньше переводили сами, а теперь отдали эту работу внештатной переводчице Кате. В целом это прекрасно и мы очень довольны. Доки наконец-то переводятся, а техписатели освободились для основной работы (привет, теория ограничений).

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

Ошибки в переводе часто встречаются там, где исходный текст написан сложно. Там могут быть сложносочинённые предложения, уточнения в скобках, путаница в местоимениях, непонятные причинно-следственные связи. Это сложно читать и понимать вообще всем, включая переводчиков.

Другой типичный случай — когда код не размечен как код. Вот мы пишем про integer. Это абстрактное «целое число» или «переменная типа integer»? Разница существенная, мы всё-таки пишем про СУБД. Если это тип данных, то мы должны выделить его моноширинным шрифтом. Например: the Lua integer type can hold integer values from _____ to _____.

Вывод такой: переводчики ошибаются там, где ошибутся и многие другие читатели. Поэтому мы (писатели) берём на себя ответственность за все систематические ошибки в переводе. Изучаем их, ищем причину, вырабатываем правило,  внедряем его. Конечно, исправляем ошибки в оригинальном тексте и помогаем переводчикам исправлять перевод.

А что значит «внедрить правило»? Задокументировать, применять в ревью новых текстов, исправлять в старых, добавить в автотесты.

Gostdown

Трогал я этот шаблон. Он так се, например, подтягивает свой шриф. Зачем, когда есть Таймс Роман.

"Этот шаблон" - это какой?