Грамотные книги.

← →
Pavia © (2015-02-10 16:26) [0]

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

← →
Ega23 © (2015-02-10 16:57) [1]

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

← →
Rouse_ © (2015-02-10 16:59) [2]

Выбирай :)
http://rouse.drkb.ru/books.php

← →
VICTOR_ © (2015-02-10 17:12) [3]

MSDN, Delphi 5 Help

← →
Германн © (2015-02-10 17:33) [4]

> MSDN, Delphi 5 Help

Ага. Особенно хорошо читается MSDN в машинном переводе )

← →
Pavia © (2015-02-10 18:50) [5]

> Выбирай :)

Если бы я мог выбрать. То бы не спрашивал, совета. Можете назвать конкретнее 1-2 книги. 1-2х авторов.

> Если по стилистике, то на какой-нибудь самиздат обратись,
> там масса всякого для начинающих графоманов.

Там в основном художественная литература. И научно популярная. Вы считаете что эти правила можно применять и в технических текстах?
И всё таки хочется конкретики.

> VICTOR_ © (10.02.15 17:12) [3]
> MSDN, Delphi 5 Help

Забыл сказать мне надо на русском языке.

← →
Ega23 © (2015-02-10 19:36) [6]

> Там в основном художественная литература. И научно популярная.
> Вы считаете что эти правила можно применять и в технических
> текстах?

Я не теоретик от литературы, но по-моему у Дивова в жеже что-то такое проскакивало. Мол, есть вполне определённые правила построения текстов.
Как НЕ НАДО писать статьи - это в "Физики шутят" была отдельная глава.
http://vivovoco.astronet.ru/VV/PAPERS/SCILANG/JOKE/JOKE2.HTM

← →
Jeer © (2015-02-10 21:19) [7]

"Книги не бывают грамотными".

Грамотными бывают люди.

← →
Inovet © (2015-02-10 22:05) [8]

Удалено модератором

← →
Jeer © (2015-02-10 23:43) [9]

Грамотные и/или умные книжки пишутся людьми, таковыми.

← →
Inovet © (2015-02-11 00:11) [10]

Удалено модератором

← →
Kilkennycat © (2015-02-11 00:27) [11]

Удалено модератором

← →
Kilkennycat © (2015-02-11 00:30) [12]

Удалено модератором

← →
Кщд © (2015-02-11 09:46) [13]

>Jeer © (10.02.15 21:19) [7]
>"Книги не бывают грамотными".
http://ru.wiktionary.org/wiki/%D0%B3%D1%80%D0%B0%D0%BC%D0%BE%D1%82%D0%BD%D1%8B%D0%B9
цитирую:
"...не содержащий грамматических и стилистических ошибок, соответствующий нормам литературного языка ◆ Вот вам пример грамотного текста.
выполненный в соответствии с основными требованиями данной области знаний ◆ Наконец-то Вам удалось сделать грамотный чертёж."

← →
Rouse_ © (2015-02-11 10:18) [14]

> Pavia © (10.02.15 18:50) [5]
>
> > Выбирай :)
>
> Если бы я мог выбрать. То бы не спрашивал, совета. Можете
> назвать конкретнее 1-2 книги. 1-2х авторов.

Ну к примеру Дональд Кнут, все 3 тома: http://rouse.drkb.ru/books.php#knut

← →
Pavia © (2015-02-11 10:39) [15]

Кнута я бы не рассматривал. Так как тех кто его прочитал можно пересчитать по пальцам одной руки. Остальные честно признались что читали и не осилили. А многие просто советуют как бараны даже не читая его. Оно и понятна один из советов звучит как каждая формула уменьшает в двое число читателей. Но стиль у Кнута изложения текста тоже ужастный.

1) Кондидат номер 1 Эндрю Таненбаум.
2) А вот кто второй Дейкстра, Окулов, Вирт?
3) Свой вариант.

← →
Kilkennycat © (2015-02-11 11:43) [16]

А когда иностранные авторы, обсуждается оригинал? Ибо переводчик еще тот переводчик может оказаться.

← →
картман © (2015-02-11 12:13) [17]

мне тут понравился стиль: http://elementy.ru/lib/431448

← →
Kerk © (2015-02-11 12:26) [18]

"Введение в ТРИЗ" Альтшуллера совершенно потрясающим языком написана.

Но корявый язык исправляют чтением художественной литературы в первую очередь. Это все от языковой бедности. Я знаю довольно хороших программистов, которые на письме и двух слов связать не могут. Это явно не из-за того, что они Таненбаума не читали. Да и какой смысл для обогащения языка его читать, если это все равно перевод?

← →
Юрий Зотов © (2015-02-11 13:56) [19]

> Pavia © (10.02.15 16:26)

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

В первую очередь - Пушкин, Чехов и иже с ними. Потому что [18].

Только ожидать ощутимого результата за пару-тройку месяцев вряд ли стоит. Даже если много читать, лексикон все равно обогащается не быстро. Да ведь есть проблемы и помимо лексикона - построение фраз, знаки препинания...

PS
А после Пушкина и Чехова - мои постинги. Для окончательной шлифовки.
:o)

← →
Kerk © (2015-02-11 14:11) [20]

Вот, кстати, что могу порекомендовать http://www.flibusta.net/b/138618
Ну а потом уже постинги ЮЗ :)

← →
pavel_guzhanov © (2015-02-11 14:12) [21]

> А после Пушкина и Чехова - мои постинги. Для окончательной
> шлифовки.

Могу даже ссылку на один дать. Только на моем сайте ;о)

← →
Mystic © (2015-02-11 15:25) [22]

Достигается упражнениями. Вообще, тема достаточно сложная.

Вполне может быть, что ты описываешь сложную тему, где использование слов не лучший вариант. Например, если в шахматной книге убрать всю нотацию, а оставить только текст, то он будет косноязычен у большинства авторов. «Ладейная пешка на королевском фланге продвинулась на поле вперед и напала на слона. Слон отступил на одно поле став на краю доски.» Конечно, нашлись бы виртуозы и с таком жанре, но их были бы единицы. Так что если ты чувствуешь, что слова не описывают так, как тебе хотелось бы, то имеет смысл подумать о чем-то кроме слов.

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

Но вернемся к читателю. Полезно поставить себя на его место и задать вопрос: «А что мне надо?» Если вместо ответа на этот вопрос читатель найдет ответ на совсем другой вопрос, то он покажется ему косноязычным, потому что не отвечает его ожиданиям. Например, человеку просто надо вызвать CreateProcess для создания нового процесса не внимая в детали. Если в книге он найдет детальное описание параметров, в которые он не хотел бы вдаваться, то текст покажется ему ужасно косноязычным. Ибо он ожидает прочитать: lpProcessAttributes - передавайте всегда NULL, если вас не интересуют извращения. Если вместо этого он начнет читать про тонкости использования SECURITY_ATTRIBUTES, которые ему не нужны, вникать в которые он не хочет, то большинство фраз пролетит мимо мозга, что усилит ощущение косноязычности. Мол пишет автор какую-то непонятную фигню.

← →
Jeer © (2015-02-11 17:08) [23]

Гра́мотность (от лат. grammatica — «учение о словесности», др.-греч. γραμματική — «словесность, грамматика») — степень владения человеком навыками письма и чтения на родном языке. Традиционно под словом «грамотный» подразумевают человека, умеющего читать и писать, или только читать на каком-либо языке.

Все остальные применения "грамотный" - от неграмотности.

Из той же серии "вкусный девайс" и пр.

← →
Кто б сомневался © (2015-02-11 17:51) [24]

В чем корявость проявляется? В терминах программирования или в самой стилистике языка? И какой язык вообще? Русский, английский?

← →
Кто б сомневался © (2015-02-11 17:54) [25]

Как пример хорошо документированного кода, могу порекомендовать сырцы VirtualTreeView

← →
картман © (2015-02-11 18:03) [26]

> В чем корявость проявляется? ...
> или в самой стилистике языка

я б сказал, в самом языке))

← →
Кщд © (2015-02-12 07:25) [27]

>Jeer © (11.02.15 17:08) [23]
>Все остальные применения "грамотный" - от неграмотности.
на приведённом ресурсе есть ссылки на словари
на всякий случай: http://www.gramota.ru/slovari/dic/?word=%E3%F0%E0%EC%EE%F2%ED%FB%E9&all=x

все остальные толкования - на совести толкователей

← →
Jeer © (2015-02-12 15:44) [28]

жаргонизм - это та же неграмотность.

Грамотные: дерево, асфальт, туалет, яблоко, глаз, сон, собака... в дополнение к книге, инженеру, молотку и чего-еще-изволите.

Остальное и сами придумаете.

после слова "дерево" я всё понял
можно было не продолжать

> Грамотные: дерево,

странно... буратино неграмотный был.

Почти не встречал непереводных (на русском языке) книг по программированию, написанных качественно, т.е. ясно, кратко и исчерпывающе. В качестве чуть ли не единственного исключения мог бы привести разве что Вострикова с Ковязиным. Переводные во многом зависят от переводчика. Но это касается не только специальной литературы, конечно :) Что касается английского контента, то, ИМХО, почти идеалом являются "родные" тексты Delphi.

По долгу "службы" приходилось сталкиваться со множеством документации и инструкций к программным продуктам. Поражало неумение (нежелание ?) авторов писАть понятно и кратко для ПОЛЬЗОВАТЕЛЕЙ. Огромное количество скриншотов, тупые фразы типа "нажмите на такую-то кнопку", и в целом абсолютное непонимание читающим а ЗАЧЕМ собственно, все это надо делать ?
Как пример, могу сослаться на руководства по MS SQL Server, ИМХО - самый показательный пример как НЕ СЛЕДУЕТ писать руководства.

Ну и последнее, резюмирующее. Писать грамотные, исчерпывающие,понятные и легкие в пользовании руководства нисколько не легче, а иногда много труднее, чем сами программы. А еще труднее (почти невозможно) научить это делать других :)

Рискую получить ушаты на свою седеющую голову,- поделюсь "секретами", на которых "собаку съел", и не одну :)
Не буду советовать как НАДО писать, посоветую как НЕ НАДО.
Итак:
1. Ни в коем случае не следует НАЧИНАТЬ руководство с описания элементов интерфейса, не познакомив достаточно развернуто с НАЗНАЧЕНИЕМ и ОБЩИМ ФУНКЦИОНАЛОМ программы.
2. Избегайте обороты типа "нажмите". Вообще следует абстрагироваться от любых местоимений, даже контекстных.
3. Не пишите длинных сложноподчиненных предложений. Слово "который" не должно использоваться в предложении более 1 раза.
4. Избегайте длинных абзацев, один вид которых пугает читателя.
5. Не следует держать читателя за дурака и тем более - за сверхразумного интеллектуала. Писать надо просто, но в меру.
6. Категорически следует избегать юмора. Вероятность 99,9 %, что ваши читатели не поймут ваши потуги на шутки.
7. Не рекомендуется "публиковать" руководство, предварительно не вынеся его "на суд" человека постороннего, например, жены или приятеля-не программиста.
8. Избегайте использования спец.терминов, а если без них нельзя, не ленитесь давать ссылки на подробное объяснение.
9. Не приступайте к написанию руководства без продуманного плана
10. Не оставляйте работу над руководством на последний момент, - пишите его по мере разработки проекта.

Очень популярная ошибка многих руководств на достаточно известные программные продукты - это эффект "исчезания леса за деревьями". Подробно написано что нажимать и в какой последовательности и при этом после прочтения текста исчезает даже намек на то, а ЗАЧЕМ ЭТО ВСЕ НУЖНО.
Т.е. пользователь во время работы с ПП сталкивается с необходимостью выполнить какие-то вполне конктретные операции, которые он прекрасно делал до этого "на бумаге". Но как это сделать с помощью программы он не знает совершенно. И после прочтения массы текста руководства так и НЕ ПОНИМАЕТ.
Иными словами надо чтобы руководство не служило для него своего рода "уставом" (кторый, как известно, понимать не требуется - его надо выполнять), а наоборот - помощью и путеводителем.
Надо, например, ему ввести новый документ (договор, платежное поручение, счет-фактуру и т.д.), нужно чтобы он мог тупо выбрать нужное из меню (оглавления) и быстро найти то, что ему КОНКРЕТНО, ЯСНО и БЫСТРО подскажет, что там нужно нажимать и зачем.

Ну и еще из личного опыта :)
Большинство пользователей, как правило, руководств не читают, если у них есть возможность общаться с авторами программы напрямую. Поэтому часто приходилось писать два "комплекта": один очень краткий, второй - развернутый. Первый - чтобы обезопасить себя от домогательств самых ленивых :)
Ну и, конечно, максимальное использование встроенных подсказок - хинтов, поясняющих подписей, ссылок на фрагменты хэлпов. ИМХО, это много эффективнее любых руководств.

> MsGuns © (15.02.15 00:44) [31]
>
> Почти не встречал непереводных (на русском языке) книг по
> программированию, написанных качественно, т.е. ясно, кратко
> и исчерпывающе. В качестве чуть ли не единственного исключения
> мог бы привести разве что Вострикова с Ковязиным.

Т.е. ту книгу которая "рекламируется" в нашей конференции "Компоненты" ты тоже считаешь "написанной некачественно"?

Удалено модератором

> [17] картман © (11.02.15 12:13)
> мне тут понравился стиль: http://elementy.ru/lib/431448

Спасибо, читаю. Хорошая научно-популярная книга.

Грамотные книги. Найти похожие ветки