Клуб технических писателей

Структура базы знаний

Кирилл Богатов
22 мая, 17:27

Здравствуйте, коллеги!

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

Например, есть описание справочника. Технический специалист хочет знать о том, как этот справочник связан с другими объектами и настройками, какие нюансы есть в его заполнении.  Для обычного же пользователя этот справочник — лишь один шаг в решении задачи.

Мешать техническое и пользовательское описание нельзя, но и усложнять структуру тоже не хочется. Пока что склоняюсь к такому варианту:

  • Главная страница
    • Общая тема
      • Инструкция 1
      • Инструкция 2
        • Шаг 1
        • Шаг 2
      • Решение проблем
      • Технические нюансы
        • Справочник 1
        • Справочник 2

Беда в том,  что связь конкретного справочника с общей темой не всегда очевидна. А значит, читателю будет тяжело найти нужную статью.

Что вы думаете о такой структуре? Как можно сделать лучше?

6 комментариев
Подписаться на комментарии к посту
Великолепный Сеня
30 мая, 04:02
Я бы разделил эти направления. Вы можете отпугнуть рядовых пользователей от своих инструкций, так как перегрузите их техническими нюансами. Также можете вызвать раздражение у технических специалистов, так как для них инструкции будут перегружены информацией для "чайников".
Кирилл Богатов
13 июня, 11:28
Великолепный Сеня,
Тогда получается такая структура:


1. Руководство пользователя
1.1. Тема 1
1.1.1. Инструкция 1
1.1.2. Инструкция 2
1.2. Решение проблем
1.3. Особенности работы


2. Техническая документация
2.1. Тема 1
2.1.1. Технические нюансы


Технические специалисты жалуются, что при таком подходе приходится искать ответ по всему руководству.
Обновлено 13 июня, 11:28
Кристина
23 июня, 14:58
База знаний это единый документ или разные? В каком формате ? При выборе каждого из пункта куда попадает пользователь? Указанное дерево - ссылки или содержание?
Может быть, сделать в справочниках относительные ссылки на общее описание и наоборот.
Может быть, поможет, если на странице с общим описанием прописать структуру всей базы, то есть дать читателям единую точку входа, с которой они будут переходить / выбирать нужный документ.
Кирилл Богатов
27 июня, 11:24
Кристина,


1. База знаний одна, но некоторые статьи скрыты от клиентов.

2. Базу знаний планируем переносить в Confluence. 
3. При выборе пункта пользователь попадает либо на статью-агрегатор, либо на статью с описанием (например, описанием справочника).
4. Указанное дерево — это иерархия ссылок. Как в хелпе Яндекса.
5. Про относительные ссылки хорошая мысль, делаем так сейчас.
6. У нас около 2000 статей, некоторые из которых является кросспродуктовыми. Идея с единой точкой входа хороша, но вопрос в том, как это грамотно сделать: по продуктам, по категориям пользователей или по пользовательским задачам? 
Можете привести примеры удачных решений?
Обновлено 27 июня, 11:24
Кристина
29 июня, 19:20
По пункту 6 сложно дать конкретный совет при таком количестве статей (2000 это прилично) - тут должно быть индивидуальное решение конкретно для вашей компании. Устройте опрос сотрудников. Только в опросе не должны предлагаться варианты решения в лоб, из него именно вам должно стать ясно, какое решение верное. Например, можно спросить "устраивает / не устраивает текущая система", "что вам неудобно" и т.п.
Кристина
29 июня, 19:25
По продуктам, кажется, должно сработать. Например, у вас 5 продуктов - это 5 основных разделов с названием продуктов. В каждом - набор ссылок на статьи разного  уровня и типа (пользовательские, технические и т. п.). Пользователь выбирает нужный продукт, а затем - нужную статью. Не хочет читать сугубо-техническую / пользовательскую - не переходит в нее.
И в таком случае на кросс-продуктовые статьи будут ссылки из всех нужных продуктов.
Обновлено 29 июня, 19:25