Организация документации: первые мысли

Кусо

Пока вопрос об организации документации открыт и обсуждается документация собрана в едином дереве в тут.

Попытаюсь сперва просто записать соображения.

• Наверное, есть смысл разбить Документацию на «Документация Пользователя», «Документация Разработчика», whatelse, и разложить это по разным кластерам. Тогда их можно будет эскпорт-импортить по отдельности и не придётся сильно извращаться для получения вики-имён. Всё-таки /Доку Ментация смотрится смешно =)

Виды документации

• Вводная документация — описание, что это такое
• /ДокументацияПользователя — описания того, как этим сервисом пользоваться
• Документация Организатора — описания для владельцев узлов и модераторов сообществ. Для тех, кто будет активно организовывать прочих пользователей. Думаю, есть смысл вынести
• /ДокументацияРазработчика — внутренние спеки разных уровней

• Важно осветить терминологические системы:
  • термины на уровне пользователей — типа «журнал», «учётная запись», «сообщество», «документ», «конфиденты», «фасет»
  • слэнг пользовательского уровня — типа «дифф», «аккаунт», «шкура», «фид»
  • термины разработчиков — типа «ядро», «нпж-объект», «хандлер», «форматтер», “nns”
  • слэнг разработчиков — типа «ананас», «рекорд-статсы», «рекорд-рефы», «нижние [рекорд-]рефы»
• Наверное, слэнга маркетологов и организаторов нет.

• перед началом документирования нужно написать содержание всех разделов документации, прикинуть требуемые объёмы по каждой главке (и тоже написать про эти объёмы). После этого писать драфтовые версии подразделов (главок) смогут все участники проекта, а координаторам остаётся только править и корректировать.