Почему вики - это классно, и как правильно ею пользоваться?

На моей работе сложилась ситуация, когда ведение базы знаний 1С превратится в боль и страдания. Конечно же, вот причины:

  • сначала думали о вики, но отказались, потому что это же надо изучать! (не согласен, погружение занимает 1 час)
  • качественный материал требует времени
  • разработчик-документатор хочет сразу написать «идеально», показать весь пласт знаний
  • дублирование

Ведя документацию и постоянно редактируя вики, я пришел к некоторым заключениям, которыми хочу поделиться.

Обратимся к философии самой вики. Вот что пишет создатель концепции Wiki (не Википедии!) Уорд Канингхем http://wiki.c2.com/?WikiDesignPrinciples

Simple - easier to use than abuse. A wiki that reinvents HTML markup ([b]bold[/b], for example) has lost the path!
Open - Should a page be found to be incomplete or poorly organized, any reader can edit it as they see fit.
Incremental - Pages can cite other pages, including pages that have not been written yet.
Organic - The structure and text content of the site are open to editing and evolution.
Mundane - A small number of (irregular) text conventions will provide access to the most useful page markup.
Universal - The mechanisms of editing and organizing are the same as those of writing, so that any writer is automatically an editor and organizer.
Overt - The formatted (and printed) output will suggest the input required to reproduce it.
Unified - Page names will be drawn from a flat space so that no additional context is required to interpret them.
Precise - Pages will be titled with sufficient precision to avoid most name clashes, typically by forming noun phrases.
Tolerant - Interpretable (even if undesirable) behavior is preferred to error messages.
Observable - Activity within the site can be watched and reviewed by any other visitor to the site.
Convergent - Duplication can be discouraged or removed by finding and citing similar or related content.

Я не буду переводить, только приведу примеры и дополню.

Wiki - быстро

Само название wiki переводится как быстро. Достаточно перейти на несуществующую страницу, как уже можно ее создавать. Существующие - править. Это действие требует 1 щелчка мыши.

  • не уверены в факте?
  • нет времени расписывать?
  • напишите своими словами и поставьте тег FIXME

Требуется обширное пояснение? Сразу ставьте ссылку на него в статью, даже если пояснения нет. Можете создать страницу потом. Или кто-то создаст ее за вас, если это коллективная вики.

Простота использования

Самый простой синтаксис, что можно придумать. Можно писать простой текст, отбивая пустой строкой, и это уже будет документом. Из минимума придется выучить как делать ссылки и заголовки. Во вторую очередь - таблицы, код, картинки. (см. принцип Simple, Mundane)

Пока писал, даже нашел способ, как переводить Word doc документы в вики.

Не нужно быть эстетом

Все и сразу - так не бывает. Напишите минимум, своим языком. Сохраните и правьте, правьте, правьте. Такое постепенное улучшение превратит вашу статью в идеальную. (см. принцип Organic)

Вот что пойдет на благо:

  • поиск по FIXME
  • поиск «статей-сирот»
  • поиск несуществующих статей

Читая статью, хотите поправить автора? Не стесняйтесь, откройте на редактирование, и сделайте текст лучше! (см. принцип Open)

Увидели ошибку в факте, но не знаете как ее исправить? Ставьте FIXME с пояснением.