Мы сейчас можем далеко уйти в этой теме, но у меня таки есть Вам сказать пару слов. Дальше будет немножечко сарказма. :)
Постараюсь, кратко и тезисно поделиться своими наблюдениями. Говорим в контексте вэба и современных инструментов, тенденций, методик и подходов (на категоричную истину в последней инстанции не претендую):
— целевая аудитория влияет => большинство пользователей (а сегодня — это вэб) хочет документацию, чтоб просто, красиво, понятно, ну и быстро находить нужное.
Посмотрите на документацию Sketch, Apple, Slack и всё сразу встанет на свои места. Подход виден сразу: авторы уважают пользователей и проявляют заботу. Почему? Потому что надо делать хорошо, ну и потому что деньги. ;)
— ворд — ад.
Он не интерактивен, неудобен, как в качестве инструмента, так и конечного формата.
Я, как и большинство пользователей, ни за что бы не стал читать документацию в ворде (ну если только за деньги :) ) и иметь дело с компанией, которая вот так относится к своим пользователям.
— всякие HATs— тот же ад, что и ворд, только по $2к за одну лиц. копию. Больше ничего не скажу, не хочу никого обидеть. :)
Исключение: писанина всяких мануалов в сугубо спец. среде и на производстве.
— ПэДэФэ — кромешный ад.
Неискушённые пользователи не станут это читать. «Потому что «фу» (и да, это таки цитата :) ).
Последние 5 лет пишу доки для вэба (документация для различных продуктов/услуг, так же документировал WP темы/шаблоны для продажи на ThemeForest), в том числе и на фрилансе.
Вышесказанное лично мои выводы, на основе моего опыта и современных тенденций индустрии, компаний и пожеланий заказчиков.
Вывод: будущее за интерактивом, вэбом, мд, ссг’эшками; будущее за документацией здесь и сейчас, вспоминаем (Николай ещё здесь писал о доке по синтаксису Раста) Elm и Rust.
В идеале, документация должна быть написана простым языком, выглядеть красиво, привлекательно и в ней должно быть легко разобраться и отыскать нужное сразу.
Ну и, я не могу не упомянуть о Томе Джонсоне, у него масса отличных материалов на поднятые выше темы. Ознакомиться можно на
https://idratherbewriting.comВорд, HATs, ПэДэФэ и еже с ними — рудименты, которые нужно оставить в 90-ых, забыть, запить и забить. ;)
Теперь можете бить меня палками, бросаться камнями, банить и вот это вот всё.
Сэ — Сарказм.
