Pull to refresh
20
0
Николай Волынкин @nick_volynkin

Технический писатель

Send message
Ну и я бы посоветовал освоить работу с патчами и 3-way merge

Пока непонятно, какую проблему это бы решило.


источников контента — тесткейсов, юзер сториз, спек, тикетов и где там еще у вас ведется внутрипроектная документация

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


Ну а ещё, внутренние доки не обязательно пишутся в разметке и лежат в репозитории с кодом. В большинстве известных мне компаний это не так.

А почему вы не конвертируете MD в RST и не пускаете все по одному пайплайну

Финальную сборку сайта делает Jekyll, а он в качестве исходников контента принимает именно MD. Исходники страниц вроде release notes у него в чистом MD + frontmatter в шапке. А страницы документации мы* сначала Sphinx'ом собираем в HTML, потом выделяем из него кусок HTML с контентом и тоже добавляем frontmatter. Тут можно вспомнить, что MD это надмножество HTML, так что по сути Jekyll собирает окончательный сайт из MD. Так что пайплайн сборки как раз конвертирует rST → MD.


*в Plesk я уже не работаю, так что это «мы» по старой памяти :)

Из коробки, похоже, нет такой возможности. И у нас ни разу не было потребности в этом. Но Sphinx легко расширяется, так что можно написать свой экстеншен. Вот пример: https://stackoverflow.com/questions/57271548/custom-section-numbering-in-sphinx, https://github.com/sphinx-doc/sphinx/issues/6614.

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


Ещё вы можете генерировать часть документации из кода. Кайф легковесных разметок вроде MD или rST в том, что их легко автогенерить.

Они дают WYSIWYG-редактор и обеспечивают (как уж могут) жизненный цикл документации (разработка-ревью-публикация). За счёт визуального редактора на них можно за день пересадить человека, который писал только в Ворде до этого. То есть, требования к квалификации писателя минимальные.


Ещё в них из коробки могут быть какие-то полезные фичи: поиск, аналитика, красивая тема оформления. Но это будет свой закрытый вендорский поиск, с починкой багов по пять лет и невозможностью что-то самому поправить.

Это XML со всеми его проблемами. Использование XML-based технологий не устраняет стену между техписателями и разработкой. По-прежнему нужно иметь специальный редактор и знать конкретную нотацию, чтобы контрибьютить в документацию. А ещё XML плохо мержится и диффается. Ну и самое главное, это более сложный инструмент, а результат условно тот же.


Однако, XML-based технологии хороши, когда у нас высокая степень переиспользования контента и/или очень много метаданных. Например, мы формируем инструкции для 1000 единиц бытовой техники, используя для этого 3000 кусочков контента. Или у нас продукт в области инфобезопасности, у него 5 активных версий и 10 ролей пользователей, которым доступны или не доступны разные фичи. Тогда мы размечаем документацию по тому, какие фичи она использует, и к каким версиям продукта подходит. А потом собираем вот эти 50 руководств для разных ролей и версий. Тут XML хорош, потому что в нём удобно навешивать метаданные на контент.

Автор не понял, что рерайтил ;)

+1, версию в имя или в параметр после имени вроде https://example.com/css/main.css?asdfasdf. Лучше не версию, а хеш-сумму файла и автоматически. И тогда можно выставлять бесконечный TTL кеширования. Подробности гуглятся по слову "cachebusting"

Действительно, очень похоже. Структура повествования та же, совпадают характерные фразы вроде "Географическая распределённость обычно ограничивается одним федеральным округом в России" → "А география передачи данных часто ограничивается одним федеральным округом".


Пойду сохраню полезные ссылки из комментариев, пока статью не удалили за плагиат.

Ага, спасибо, это полезное уточнение. Не задумывался как-то, что bootstrapcdn принадлежит Google.

Кстати, есть плагин для FF под названием HTTPS everywhere, он запрещает загрузку ассетов по HTTP как раз для приватности. Может и для Хрома есть такой же.

Большое спасибо, пойду читать!

При всем этом за услуги сети доставки контента нужно платить. А плата чаще всего зависит от объема передаваемого трафика.

За трафик в любом случае придётся платить. А трафик с CDN'а может быть сильно дешевле, чем трафик с обычного хостера, на котором у вас сайт.

А почему именно Google? Что CDN эту информацию получает, это понятно.
Ну и, кстати, эти же блокировщики допускают загрузку с CDN'ов популярных библиотек вроде jQuery.

А как HTTP2 помогает с картинками? Честно, не знаю, но очень интересно. Вот только на прошлой неделе занимался производительностью страниц и в том числе картинками.

В опросе не хватает вариантов «пробовал и предпочитаю SSG без CMS». А пост отличный, спасибо!

Сфинкс сам по себе поддерживает бесконечную вложенность документов, причём уже давно. Плагин для публикации в Конфлюенс тоже таких ограничений не накладывает, у меня прямо сейчас 4 уровня в одном проекте, и то много.

Почему вы сделали новый CI/CD, а не интеграцию c TeamCity?

Спасибо за термины "infrastructure as bash history" и "documentation as bash history"!

Привет! Вы использовали наши с Александром Баракиным иллюстрации из ответа о проблеме XY. Классно, что они и к вашей статье подошли. Как и всё на SO, они были опубликованы под лицензией CC-BY-SA. Пожалуйста, укажите авторов и дайте ссылку на источник.

Information

Rating
Does not participate
Location
Новосибирск, Новосибирская обл., Россия
Works in
Date of birth
Registered
Activity