meta data for this page
2022-10-12 Новый подход в составлении комплексных инструкций на данной вики
Сегодня я начинаю работу над руководством администратора для системы Росплатформа. Формат, думаю останется прежним, который успешно себя зарекомендовал:
- Пишу на wiki;
- Переношу в проект;
- Вычитываю и правлю сам;
- Обрезаю и подписываю рисунки при необходимости;
- Отдаю техническому писателю.
С одной стороны почти все руководства которые я пишу и размещаю на данном ресурсе для Enterprise продуктов созданы для конкретных платных проектов нашей компании, с другой стороны я как автор данных руководств имею право распоряжаться ими по своему усмотрению, если иное не предусмотрено трудовым договором. Поэтому в принципе публикация черновых вариантов на данном ресурсе не противоречит деловой этике.
Основная идея которая закладывается в вики - это совершенствование материала. Я не переписываю одни и те-же статьи заново каждый раз, не публикую отдельную статью если её необходимо доработать под текущие задачи. Материал должен быть атомарным и совершенствоваться в каждой своей итерации. Именно поэтому я делю каждую большую статью на много маленьких - простых функций которые по отдельности могут быть использованы для создания другой комплексной статьи. И с улучшением составных компонентов комплексных статей - улучшается и итоговый материал.
В данном руководстве я пробую применить новый подход, который должен помочь мне решить такие проблемы:
- Отслеживание готового материала и планов по написанию разделов документа;
- Отсутствие структуры автоматического оглавления страниц;
- Перегрузка сервера при открытии сводной страницы руководства со всеми включениями;
- Практическая бесполезность сводной страницы кроме как для экспорта в PDF или odf;
Для этого я составил сводную таблицу разделов будущего руководства на странице Руководство Росплатформа. В таблице отражены все необходимые разделы а также дополнительная информация: из какой консоли администрирования необходимо выполнять данную операцию, воздействие на инфраструктуру от выполнения данной операции. В таблицу будут включены ссылки на соответствующие дочерние страницы.
Я по прежнему в конечном счёте буду вынужден свести все страницы в одну сводную страницу вики, но возможно не буду публиковать ее для общего доступа а использую только для экспорта в проектную документацию.