Комментарии 38
Очень интересная информация, спасибо. Вопрос о справочной документации для меня на данный момент очень актуален. Не думал, что существуют компании специализирующиеся на подобных услугах.
«Для вас важно качество» → «Нет» → «Wiki» — это как вообще?
FAQ — это если не срочно, а Getting Started — срочно. Каша какая-то.
FAQ — это если не срочно, а Getting Started — срочно. Каша какая-то.
Тут имеется в виду, что wiki пишут и редактируют сами пользователи. Поэтому отсутствует единый стиль, и возможны ошибки и неточности. Но если wiki будет редактироваться командой технических писателей, то качество, конечно, не пострадает.
Выходит, в одном месте один критерий, в другом другой, в этом конкретном случае критерий — источник информации, но вы его называете «экономия» или «качество». Примерно это я и называю кашей. По вашей схеме невозможна ситуация, когда компания использует wiki, но наполняют её сотрудники; или ситуация, когда экономить компания не хочет и всячески поощряет качественный вклад, и наполняют все — и пользователи, и сотрудники, и т.д…
«Вики, которое заполняется сотрудниками» — это в системе ценностей автора статьи скорее «online help», а не «wiki». Online help можно делать на чём угодно. Можно весь сайт делать на вики, но давать права редактирования только сотрудникам — сайт от этого, ИМХО, «вики» не станет, даже если использовать вики-движок.
Мне кажется Вы придираетесь. Схема вполне понятна и читаема.
И, да, вики всё таки уступает по качеству хотя бы тем, что выглядит не особо презентабельно кто бы её ни наполнял. Кроме того, не совсем на это она ориентирована и что бы там в итоге не оказалось, это будет обычная база знаний и не более того.
И, да, вики всё таки уступает по качеству хотя бы тем, что выглядит не особо презентабельно кто бы её ни наполнял. Кроме того, не совсем на это она ориентирована и что бы там в итоге не оказалось, это будет обычная база знаний и не более того.
уступает по качеству хотя бы тем, что выглядит не особо презентабельно
Чему уступает-то? Вы понимаете, что тёплое с мягким сравниваете? Не говоря о том, что сам тезис «wiki выглядит не особо презентабельно» я подвергаю сомнению (это если предположить, что вы имеете ввиду конкретный шаблон интерфейса — самым распространённым является стандартный шаблон Wikipedia, потому что если нет, то тогда вообще непонятно, что вы имеете ввиду).
И вы так говорите «база знаний», как будто это что-то плохое =)
+1 к IIIEB4YK. То, что непрезентабельно — бред номер один. MediaWiki + расширения => можно отменной красоты навертеть (мы у себя 75 расширений используем [сборка mediawiki4intranet], а Wikimedia вообще аж ~140). Без расширений, конечно, менее красиво.
Аналогично, если вы просто поставите движок и, ничего больше не делая, будете думать, что тут же прибегут пользователи и всё за вас напишут — то да, будет некачественно. :-) Но если самим активно заниматься наполнением — вики-системы для документирования круты, потому что легко вносить изменения.
Так что нужно как минимум уточнять, кто её будет наполнять. :-)
Аналогично, если вы просто поставите движок и, ничего больше не делая, будете думать, что тут же прибегут пользователи и всё за вас напишут — то да, будет некачественно. :-) Но если самим активно заниматься наполнением — вики-системы для документирования круты, потому что легко вносить изменения.
Так что нужно как минимум уточнять, кто её будет наполнять. :-)
Help & Manual, а потом хоть pdf, хоть chm, html или word :)
А диаграммки вы где рисовали такие? Случайно не в Gliffy.com?
Картинки в чем рисовали?
А есть ли специализированные сервисы, заточенные под написания справок?
Вы имеете в виду редакторы справки, позволяющие работать в облаке?
Или компании, которые вам напишут мануал?
Или компании, которые вам напишут мануал?
Редакторы справок on-line.
тогда вам скорее всего нужна wiki:
www.mediawiki.org/wiki/MediaWiki
www.atlassian.com/software/confluence/overview/technical-writing-software
www.zoho.com/wiki/help-authoring-tool.html
или www.author-it.com/
www.mediawiki.org/wiki/MediaWiki
www.atlassian.com/software/confluence/overview/technical-writing-software
www.zoho.com/wiki/help-authoring-tool.html
или www.author-it.com/
из параллельной области, но вдруг видели — есть ли такие гибриды вики и doxygen/PHPDoc/Javadoc? То есть редактирование документации кода из вики-сайта с push-ем в репозиторий
Возможно, я Вас не так понял, но посмотрите readthedocs.org
эмм, кажется, это не то.
Вот есть у меня документация к коду с описанием классов и функций (генерируется из кода), типа такой:
semantic-mediawiki.org/doc/
Хочется иметь кнопочку Edit, которая бы позволила поправить эти описания, а эти поправки бы закоммитились в исходный код.
Вот есть у меня документация к коду с описанием классов и функций (генерируется из кода), типа такой:
semantic-mediawiki.org/doc/
Хочется иметь кнопочку Edit, которая бы позволила поправить эти описания, а эти поправки бы закоммитились в исходный код.
Semantic MediaWiki — если нужна мощь и перестраивание контента
DokuWiki — если самое важное — это простой синтаксис
DokuWiki — если самое важное — это простой синтаксис
Извиняюсь, дубль
Еще можно добавить, что для компиляции справки .chm для языков, отличных от английского, нужно использовать специальный хак: www.steelbytes.com/?mid=45
Компилятор делался майкрософтом более десяти лет назад, еще в доюникодные времени, и языки, отличные от английского, воспринимает… забавно.
Компилятор делался майкрософтом более десяти лет назад, еще в доюникодные времени, и языки, отличные от английского, воспринимает… забавно.
Подробнее можно?
А то по ссылке лишь фраза «a command line clone of Microsoft AppLocale :-)» и ссылка для скачивания…
А то по ссылке лишь фраза «a command line clone of Microsoft AppLocale :-)» и ссылка для скачивания…
Конечно. Набираем в гугле «applocale chm» без ковычек и видим много инструкций и описаний самой проблемы, например вот:
www.it-authoring.com/bb/helpauth/viewtopic.php?f=22&t=9713
www.it-authoring.com/bb/helpauth/viewtopic.php?f=22&t=9713
Правильная справка должна быть контекстной, встроенной в интерфейс, без перехода «в справку».
Если интерфейс перегружен элементами, то повсеместная контекстная справка будет последним гвоздём в крышку его гроба.
Ну так необязательно всё завешивать вопросиками (
), можно, скажем, на F1 открывать overlay, в котором что-то подписано и т.п. Или окошко, в котором в свободном виде можно задать вопрос, при этом учитывается текущий контекст (если я в меню Икс, и спрашивают об Игрек, то более релевантными результатами считаются «Икс+Игрек»).
), можно, скажем, на F1 открывать overlay, в котором что-то подписано и т.п. Или окошко, в котором в свободном виде можно задать вопрос, при этом учитывается текущий контекст (если я в меню Икс, и спрашивают об Игрек, то более релевантными результатами считаются «Икс+Игрек»).Wiki — некачественно, но экономно. Не согласен, это скорее уж «голая вики»
Для устранения проблем с открытием CHM файлов, загруженных из сети, можно использовать бесплатную утилиту HHReg.
Я вообще открываю контекстное меню такого файла и ставлю галочку, что его можно просматривать.
Но тот факт, что в майкрософте заставляют пользователей вот так делать говорит о том, что скорее всего этот формат отправят в историю со временем.
EXE (e-Book) — исполняемый Windows файл. Плюсы: не требуется дополнительное ПО для просмотра.
Вот тут не понятно — что такое дополнительное ПО. Для CHM и HTML тоже не нужно дополнительное ПО, не входящее в стандартную поставку операционной системы. Ну а вообще многие такой хелп даже побоятся открывать. Даже дистрибутивы для виндовса часто поставляют не как exe файлы, а как msi пакеты. Возможно о таком формате даже упоминать не стоило.
Я вообще открываю контекстное меню такого файла и ставлю галочку, что его можно просматривать.
Но тот факт, что в майкрософте заставляют пользователей вот так делать говорит о том, что скорее всего этот формат отправят в историю со временем.
EXE (e-Book) — исполняемый Windows файл. Плюсы: не требуется дополнительное ПО для просмотра.
Вот тут не понятно — что такое дополнительное ПО. Для CHM и HTML тоже не нужно дополнительное ПО, не входящее в стандартную поставку операционной системы. Ну а вообще многие такой хелп даже побоятся открывать. Даже дистрибутивы для виндовса часто поставляют не как exe файлы, а как msi пакеты. Возможно о таком формате даже упоминать не стоило.
> Но тот факт, что в майкрософте заставляют пользователей вот так делать говорит о том, что скорее всего этот формат отправят в историю со временем.
Как бы туда MS на отправили, со временем-то. Любят они форматы придумывать и забывать — это придает им уверенность, что они не просто на гребне прогресса, но и сами по себе этот гребень создают.
Заставлять юзеров делать что-то лишнее — не самое мудрое. Лучше бы обезопасили формат в смысле замены движка вывода на что-то более надежное и недырявое, чем ядро IE.
Самое же неприятное, что де-факто документацию чаще всего делают либо в (не побоюсь, убогом, с точки зрения работы с текстом) .pdf-е, либо в .html (плюс папочка с css и изображениями), либо в .rtf/.ods — больше-то ничего кроссплатформенного, да еще и открывающегося у всех, нет. MS, вместо чем выпустить недырявое ПО для просмотра .chm под все ОСи вокруг, старательно забыло про него, так что неплохой (по идее своей) формат так и не стал «наименьшим общим знаменателем». Жаль.
Как бы туда MS на отправили, со временем-то. Любят они форматы придумывать и забывать — это придает им уверенность, что они не просто на гребне прогресса, но и сами по себе этот гребень создают.
Заставлять юзеров делать что-то лишнее — не самое мудрое. Лучше бы обезопасили формат в смысле замены движка вывода на что-то более надежное и недырявое, чем ядро IE.
Самое же неприятное, что де-факто документацию чаще всего делают либо в (не побоюсь, убогом, с точки зрения работы с текстом) .pdf-е, либо в .html (плюс папочка с css и изображениями), либо в .rtf/.ods — больше-то ничего кроссплатформенного, да еще и открывающегося у всех, нет. MS, вместо чем выпустить недырявое ПО для просмотра .chm под все ОСи вокруг, старательно забыло про него, так что неплохой (по идее своей) формат так и не стал «наименьшим общим знаменателем». Жаль.
CHM не может стать наименьшим общим знаменателем, потому что мелкомягкие с каждой версией винды, с каждой версией вижуал студии выдумывают по новому формату справки.
HLP: WinHelp (на базе извращений с RTF, был запуск приложений с помощью кнопок и прочие прелести...) — выпилили почти полностью.
Где-то там в промежутке эксперименты с конвертацией из HTML…
CHM: HTML Help (HTML с картинками и всякими индексами в архиве) — из-за какой-то «уязвимости» стало нужным запихивать в архив при выкладывании в Сети.
HXS: Microsoft Help 2
MSHC: Microsoft Help Viewer aka Microsoft Help 3 (выпилили индексы, «оно само как-нибудь» — теперь установка не «мержит» справку по два часа, а индексирует по два часа — технологический прорыв)
HLP: WinHelp (на базе извращений с RTF, был запуск приложений с помощью кнопок и прочие прелести...) — выпилили почти полностью.
Где-то там в промежутке эксперименты с конвертацией из HTML…
CHM: HTML Help (HTML с картинками и всякими индексами в архиве) — из-за какой-то «уязвимости» стало нужным запихивать в архив при выкладывании в Сети.
HXS: Microsoft Help 2
MSHC: Microsoft Help Viewer aka Microsoft Help 3 (выпилили индексы, «оно само как-нибудь» — теперь установка не «мержит» справку по два часа, а индексирует по два часа — технологический прорыв)
Консольное приложение для *Linux, *BSD, *nix? -> man
Не всё так просто :)
man скорее соответствует getting started или короткой справке, иначе лучше GNU info, соответствующий user manual. Хотя бы из-за гиперссылок.
Ну и про вывод ещё более короткой справки чем man при указании ключика -h или --help забывать не нужно. Производит впечатление сырого ПО, если они не работают. Конкретно на меня даже графическое ПО, не выводящее справку на -h (например, Skype) производит впечатление сырого и не предназначенного для конечного пользователя.
man скорее соответствует getting started или короткой справке, иначе лучше GNU info, соответствующий user manual. Хотя бы из-за гиперссылок.
Ну и про вывод ещё более короткой справки чем man при указании ключика -h или --help забывать не нужно. Производит впечатление сырого ПО, если они не работают. Конкретно на меня даже графическое ПО, не выводящее справку на -h (например, Skype) производит впечатление сырого и не предназначенного для конечного пользователя.
Надо еще приписать — «и обновлять справку постоянно!» И обязательно указывать, для какой версии подходит описание, и когда (дата) оно написано.
А то хуже нет, когда что-то надо срочно найти/сделать, а документация на официальном сайте содержит описание функционала и настроек позапрошлой major версии, да еще с припиской, что вообще оно работает глючно и лучше не пользоваться. Тогда как в нынешней ветке не только все доточили, но оно и десяток новых опций приобрело.
А то хуже нет, когда что-то надо срочно найти/сделать, а документация на официальном сайте содержит описание функционала и настроек позапрошлой major версии, да еще с припиской, что вообще оно работает глючно и лучше не пользоваться. Тогда как в нынешней ветке не только все доточили, но оно и десяток новых опций приобрело.
О качестве вашей работы можно судить по наглядности материала.
Я не оцениваю содержимое, а именно оформление и доступность.
Молодцы!
Я не оцениваю содержимое, а именно оформление и доступность.
Молодцы!
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Виды и форматы справок