Две вики

В нескольких проектах, где я участвовал на ведущих ролях, и которые по разным причинам оставлял, под конец у меня всегда возникало возвышенное желание написать к ним большую подробную документацию. Чтобы другому человеку, который подхватит проект после меня, не приходилось уничтожать себе мозг слишком большим количеством предположений, отчего это сделано так, а не эдак, и вопросов, где начинать искать хвост какого-нибудь бага.

Я, кстати, люблю писать документацию. Что для программиста, как я подмечал, редкость. Причем, мне серьезно кажется, что у меня это получается довольно неплохо (пока никто вслух не жаловался :-) ). Удается, знаете ли, описать все системно, чтобы текст не выглядел как набор разрозненных примечательных фактов из истории проекта, а чтобы описание развивалось от общего к частному, и чтобы читающий всегда знал, куда посмотреть, чтобы найти, что ищет.

Но меня всегда преследовала одна очень гадкая проблема: я никак не мог дописать все, что запланировал.

Соберешься, так, что-нибудь заканчивать и думаешь, что впереди аж две недели, и уж за них-то все можно не то, что документировать, но и учебный курс написать с картинками и аудиокассетами. Начинаешь потихоньку писать, по ходу планируя следующие разделы в виде заготовленных ссылок... И тут — раз! Последняя пятница. А из заготовленных ссылок едва половина заполнена хоть чем-то, да и то не до конца дописаным. Обидно.

Вчера же произошло в некотором роде знаменательное событие. Сдавая текущий проект, я написал полностью все, что планировал. И общее описание, и описание отдельных компонентов, и справочники по классам и функциям (хотя их-то неплохо было бы писать еще во время программирования). И даже инструкцию по установке, и даже ссылки на документацию к библиотекам. Замечательно...

Раньше свою документацию я писал, в чем придется, от Word'а до HTML'а в текстовом редакторе. Но какое-то время назад мой коллега практически принудил меня попользоваться wiki (Серега, спасибо!), хотя я долго сопротивлялся, говоря, что вся идея просто кошмарна. Я был неправ. Wiki резко повысила мою продуктивность, потому что вдруг оказалось, что о куче мелочей, сопровождающих документирование, уже позаботились умные люди, и все, что тебе остается — просто писать текст.

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

Той моей первой wiki, которую я не просто видел, а реально пользовался, была WackoWiki. И ту документацию я не закончил. Последний же проект я документировал в другой — DokuWiki. И теперь я думаю, что эта работа завершилась успешно не в последнюю очередь благодаря тому, что эта wiki мне нравится больше предыдущей. И теперь я хочу поделиться, почему именно.

Сравнение

Сразу оговорюсь, что я, конечно, никакой не "эксперт", не проводил вдумчивых анализов, и скорее всего, некоторые проблемы решаются какими-нибудь настройками. И все это в любом случае субъективно.

Внешний вид

Это самое первых приятное впечатление от Doku — она гораздо симпатичней Wacko. Особенно мне не нравились в Wacko несуществующие ссылки, вот сравните:

А еще у Doku иконка симпатичная :-).

Автоматические ссылки

Одна из концепции многих wiki-систем — делать автоматические ссылки из слов НабранныхВCamelCase. Предполагается, что человек пишет текст, и когда в нем встречается термин, на который надо сделать ссылку, он просто пишет его без пробелов. Это придумал англоговорящий человек для своего языка. А в русском языке, как известно, существительные склоняются, и это очевидно напрочь убивает всю фичу. Поэтому в документации на русском языке все ссылки делают вручную.

Зато в документации программного проекта очень часто встречаются названия идентификаторов в этом самом CamelCase. И вот делать ссылки из них обычно не надо. По крайней мере автоматически, потому что даже если идентификатор описан в каком-то справочнике, вероятней всего это не отдельная страница и название у ней другое.

Wacko настаивает на создании таких ссылок. Поэтому мой текст вечно был в знаках вопроса в тех местах, где никогда ссылок не будет. Чтобы их убрать, приходилось перед каждым идентификатором в тексте ставить значок "~", что неудобно.

Doku автоматических ссылок не создает (хотя в конфиге можно включить).

URLизация ссылок

Одна из нерешенных проблем русского интернета: как загнать русские слова в URL, чтобы не было криво. Можно загнать как есть, но тогда они кодируются в некрсивые %XX. Можно переводить их в транслит, но это тоже не шибко лучше.

Doku делает проценты, а Wacko — транслит, и здесь я предпочтение никому отдать не могу, все плохо :-). Просто не смотрю на URL.

Зато что я точно понял, что названия страниц надо делать желательно из одного слова в единственном числе и именительном падеже. Так гораздо проще ставить потом ссылки в тексте, когда не приходится вспоминать, как же именно названа страница.

Синтаксис в общем

Синтаксис Wacko богаче. И это мне тоже не нравится, потому что есть много способов сделать одну и ту же вещь. Например, там есть специальный тег (??...??), которым можно задать вопрос и привлечь внимание. А есть специальный тег, которым просто привлекается внимание (!!...!!). Разные люди пользуются то одним, то другим.

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

Одна из фич Wacko, насколько я понимаю, это то, что синтаксис не использует символов, которые недоступны в русском режиме клавиатуры, чтобы не заставлять человека переключаться туда-сюда. Это было бы очень большим плюсом, если бы не то обстоятельство, что в программной документации все равно постоянно приходится переключаться: много идентификаторов и англоязычных названий. Поэтому этот плюс небольшой.

Заголовки

В рассматриваемых вики (да и в большинстве других) заголовки оформляются отвратительно.

Wacko:

== Первый уровень ==
=== Второй уровень ===
==== Третий уровень ====

Doku (еще хуже):

====== Первый уровень ======
===== Второй уровень =====
==== Третий уровень ====

Во-первых плохо то, что надо повторять одинаковое число знаков до и после, это не для людей занятие. Нет, может и не надо, но я никогда не находил времени, чтобы проверить, и уж точно никогда не запомню, где оно надо, а где нет. Наверное отчасти из-за этого в обеих вики для оформления заголовков есть кнопочки над полем редактирования. И тут Doku сильно выигрывает: для них есть просто запоминаемые клавиши: Alt+1, Alt+2... Это важно, потому что необходимость обращаться к мышке при наборе больших объемов текста напрягает.

Но такие заголовки в любом случае трудно читать из-за того, что количество знаков не совпадает с уровнем заголовка, и каждый раз приходится напрягаться и высчитывать.

Кстати, обоих этих недостатков лишен синтаксис Markdown, которым я пишу этот блог:

# Первый уровень
## Второй уровень
### Третий уровень

Вообще, если бы была хорошая вики с markdown-синтаксисом, это было бы замечательно. Заголовки — это не единственное, где он лучше.

Оглавление

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

В Wacko надо каждый раз вписывать тег, который обычно идет в начале, а значит отодвигает сам текст ниже.

Примечания

В Doku примечания превращаются в сноски, которые относятся в низ страницы, как в книжках. Это было бы неудобно читать, но при наведении мышки на сноску ее текст всплывает рядом в подсказке (не браузерной, а javascript'овой, поэтому туда можно написать много, и там работает форматирование). Поэтому их менее неудобно читать. Хотя и симпатично :-).

Примечания в Wacko оформляются обычно просто мелким текстом. Без извратов.

Таблицы

Тут на 117,3 очка вперед выигрывет Doku. Вот ее синтаксис:

^Заголовок  ^Заголовок  ^
|Текст      |Текст      |
|Текст      |Текст      |

Еще Doku умеет задавать выравнивание исключительно интуитивно понятным способом — достаточно двух пробелов с противоположной стороны:

|Налево  |  По центру  |  Направо|

И еще colspan'ы может задавать...

|Текст   |Текст на две колонки  ||
|Текст   |Текст        |Текст    |

А вот Wacko:

#|
||Текст|Текст||
||Текст|Текст||
|#

То есть Wacko настаивает на том, чтобы начало и конец таблицы, а также начало и конец строк, оформлялись вручную. Doku делает это самостоятельно. Да и ничего дополнительного — заголовков, выравнивания, colspan'ов — в Wacko, похоже, нет.

Код

Кусок кода в Doku оформляется просто отступанием всего куска на два пробела слева. Просто и читаемо. Если текст сдвигать не хочется, то его можно вместо этого заключить в теги <code>..</code>. С тегами можно задать и посветку синтаксиса: <code html>.

В Wacko блоки оформляются чуть менее элегантно на мой вкус: %%(html) .. %%.

Но вот что мне в ней действительно не понравилось, это то, что моноширинной текст, который я обычно использую для идентификаторов внутри текста, она еще зачем-то подкрашивает противным желтым фоном.

Решающие моменты

Но среди всего прочего окончательно меня склонили в сторону Doku еще два момента.

В Wacko меня преследует одна штука, которая, правда, вполне может быть связана исключительно с браузером. Во время редактирования страницы, чем больше я что-то стираю и пишу, тем больше весь процесс начинает тормозить. Доходит до того, что написанное предложение начинает медленно появляться в окне по паре букв в секунду... Раздражает слегка :-)

Самый для меня сильный плюс Doku — это редактирование по разделам. Она автоматически бьет текст от заголовка до заголовка на разделы, в кторых висит кнопочка "edit", по которой этот раздел можно отредактировать отдельно от всей страницы. Этим решается неудобство, когда при переходе в режим редактирования особенно длинной странице очень трудно найти место, которое хотелось поправить в дли-и-инной textarea. Во многом тут уже точно виноват мой Firefox, который не в состоянии делать поиск внутри textarea (древний баг), но мне приятно, что с Doku я от этого не страдаю.

HTH!.