Как научиться создавать полезную проектную документацию ИТ-систем
Бесполезная проектная документация - бич многих современных IT-инфраструктур, в том числе и тех, которые сделаны грамотно и на совесть самыми настоящими мастерами своего дела. Увы, документы для их продукта сложно поддерживать актуальными, а найти в них нужную информацию оперативно бывает очень трудно. Как же научиться создавать полезную проектную документацию IT-систем?
Есть несколько основных принципов, усвоение которых совершенно необходимо для этого! Давайте их перечислим.
Структурность
Никто не станет читать документацию от корки до корки более одного раза (да и то не факт). Будут ли к ней обращаться время от времени? Зависит от того, насколько просто можно найти в ней конкретные ответы на конкретные вопросы. А это напрямую зависит от понятной структуры, которая должна максимально упростить получение нужной информации!
Полнота, целостность и единообразие
"Причесанность" документации - очень важная составляющая. Если вы указываете какую-то техническую характеристику, то везде должны называть ее одинаково и указывать ее для всех элементов, где она есть. Тогда при внесении в документы изменений и правок не придется выискивать разнообразные наименования одного и того же - можно будет воспользоваться элементарным поиском по документу!
Форматы и определенность адресата
Документация инфраструктуры, инструкция по эксплуатации, план на случай ЧС - это все разные вещи. Так что лучше писать сразу три вида документов: описание системы, инструкцию техподдержки и инструкцию пользователя. Это поможет индивидуализировать посыл, контролировать сложность документа и доносить через него именно то, что будет полезно в данном случае, не допуская зашумления лишней информацией.
Таблицы и списки
Простыня текста - вообще не то, что вам нужно. Иногда документацию пишут, как эдакое повествование - это хуже всего, т.к. искать в таком документе почти невозможно. Сухость, информативность, где получается - список, где возможно - таблица! Идеально - если вообще нет перечислений (только списки), а все имеющие значение характеристики, параметры и показатели упорядочены в таблице.
Доходчивость
Цель нашего документа - быть полезным, а для этого ему в первую очередь нужно быть понятным. Постарайтесь обойтись в нем без профессионального сленга, ненужных сокращений или иноязычных (английских) оборотов. Не используйте аббревиатуры или же поясняйте их, используйте скриншоты - особенно в пользовательской инструкции! Фотографии оборудования будут полезны в описании системы и инструкции для техподдержки.
Проверка
Вряд ли вы сможете отдать свой текст на профессиональную редактуру, так что придется справляться своими силами. Ищите ошибки, читайте и перечитывайте текст на свежую голову, используйте проверочные сервисы, может, покажите текст коллеге. Все-таки будет очень обидно, если важная техническая информация ускользнет от пользователя из-за кривой формулировки!
