Previous Entry Share Next Entry
2016-01

Как правильно излагать очевидные для себя вещи?

Собственно, сабж. В последнее время вопрос весьма актуален.

- как писать документацию?
- как изложить в письменном виде "подразумеваемые правила" (поведения на форуме, например)?
- как излагать best practices? (частный случай той же документации)
- как, вообще, правильно выгружать содержимое своей головы в чужие?

В интерактивном режиме (1:1) у меня плюс-минус получается. Также, получаются всякие примеры и walkthroughs (хз как это адекватно перевести), где структура текста плюс-минус понятна.

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

Что почитать? Как это вообще называется (какие ключевые слова для поисковиков брать)?

This entry was originally posted at http://wizzard.dreamwidth.org/266126.html. It has comment count unavailable comments. Please comment there using OpenID.

  • 1
wizzard0 February 17th, 2013
Хорошая мета-презентация, да. А где почитать про изложение тех самых деталей, в которых дьявол?

(Deleted comment)
wizzard0 February 17th, 2013
FAQ может неплохо дополнять доку, но как составить список вопросов, если ответы для тебя очевидны?

the_aaa13 February 17th, 2013
Использовать кого-то, для кого не очевидны?

wizzard0 February 17th, 2013
Надо попробовать. А как потом их структурировать? (Я пытаюсь сконденсировать ~1500 страниц текста до ~50-100)

the_aaa13 February 17th, 2013
Если у тебя есть 1500 страниц очевидных вещей - то что-то уже пошло не так.

wizzard0 February 17th, 2013
Это статьи. Очевидные они для меня, потому что я их прочитал, запомнил и отделил в своей голове воду (например, банально не самые оптимальные варианты рассмотренных алгоритмов) от не-воды (то, что стоит реализовывать в нужных мне случаях)

the_aaa13 February 18th, 2013
Обычно люди пишут статьи о неочевидных вещах. Они задаются каким-то неочевидным вопросом, и приходят (или не приходят) к ответу на него. После чего ответ на вопрос становится известным. (или становится известно что вопрос очень сложный) Это еще не делает ответ на вопрос очевидным.

wizzard0 February 18th, 2013
Э... И при чем тут это?

Человек задался неочевидным вопросом. Написал статью. Я ее прочитал. Реализовал. Теперь для меня это очевидно (==мозг оптимизировал цепочку рассуждений до "вот есть результат, его можно использовать"). Поскольку цепочки в мозгу нету, то мне сложно ее реконструировать и изложить.

Так понятно?

the_aaa13 February 18th, 2013
Ну вот очевидна проблема - твой мозг при анализе теряет кучу важной информации. Это плохо. Нужно работать над собой и своим восприятием информации.

wizzard0 February 18th, 2013
М-ммм. Это не бага. Это фича. Иначе бы я не мог анализировать такое кол-во информации и держать ее в голове одновременно.

Бага в том, что эта фича не умеет по необходимости выключаться.

the_aaa13 February 18th, 2013
Ну, вообще говоря, таки бага, так как целостные блоки информации хранятся проще, и в целом полезнее разрозненных результатов.

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

wizzard0 February 18th, 2013
> и в целом полезнее разрозненных результатов.

результаты не разрозненные, они вполне целостные. только целостные для другого подмножества целей

а вот к мысли мы пришли толковой, да. перечитывание статей в соседнем окне с написанием доки помогает.

_winnie February 17th, 2013
1) Очевидно же, тестирование на хомячках. Просим разобраться людей, они тупят и спрашивают, фиксируем то что они часто спрашивает и где тупят (по ссылке - мониторинг вопросов на форумах).

2) Сбросить документацию на падавана, он разберётся и автоматом зафикисирует то, что ему было непонятно (немного опасно, так как люди разные, и то что понятно 1/5 людей, непонятно 4/5).

3) Вот здесь немного по теме, как работать с пользователями библиотеки - http://www.slideshare.net/jeresig/open-source-success-jquery

4) Интуиция, по своим разборками с чужими либами. Опасно, понятно почему.

Edited at 2013-02-17 02:17 pm (UTC)

nponeccop February 17th, 2013
Удивлен, что никто не знает, как это называется.

Называется writing. Гугление writing выдает кучу учебных курсов.

Writing делится на fiction и nonfiction. Essays, journals, diaries, documentaries, histories, scientific papers, photographs, biographies, textbooks, travel books, blueprints, technical documentation, user manuals, diagrams and some journalism are all common examples of non-fiction works.

A technical writer (also called a technical communicator) is a professional writer who engages in technical writing—designing, creating, and maintaining technical documentation. This documentation includes online help, user guides/manuals, white papers, design specifications, system manuals, project plans, test plans, etc.

Engineers, scientists, and other professionals may also produce technical writing, but often hand it off to a professional technical writer for proofreading, editing, and formatting. A technical writer produces technical documentation for technical, business, and consumer audiences.

maxim February 17th, 2013
Интересно, а блоггинг -- это вид текникал врайтинга ?

nponeccop February 18th, 2013
текникал блоггинг - ес.

si14 February 17th, 2013
Лев Валкин недавно написал прямо-таки прекрасный пост на эту тему, рекомендую пройтись по ссылкам на публикации там: http://lionet.livejournal.com/123634.html

  • 1
?

Log in

No account? Create an account