如何编写教程 [英] how to write a tutorial

问题描述

我最近开始阅读python教程。
http://python.org/doc/2.3.4/tut/tut.html


以下是一些快速评论：


快速示例：

如果输入字符串太长，它们不会截断它，但返回它

不变;这会弄乱你的列布局，但这通常比替代方案好一些，这可能是一个值。 （如果

你真的想要截断，你总是可以添加切片操作，如

" x.ljust（n）[：n]"。


更好：

如果输入字符串太长，它们不会截断它，但返回它

不变;

-----------------

delete：反向引号（``）等同于repr（），但它们的用途是

气馁。

-----------------

类似地，很多地方都提到不加批判的信息如警告或

应删除对其他语言的引用。


教程应该简单，简洁，至关重要，并坚持不懈。 >
也许应该删除教程的1/5长度以获得更好的效果。

遵循上述原则。


通常在整个段落中在一些所谓的计算机科学上，应该删除
的术语。他们有更多的东西来展示愚蠢的技术性，而不是帮助读者。（相关的，许多passag使用

的术语应该改写为无用的行话。例如可变对象。）


理解这些原则的一个简单方法是将perl的

文档或unix手册页与Python的文档进行比较。前者往往是无关紧要的，漫无目的，没有待机（这样写的就是它不必要地要求读者知道很多其他的

件事）。 Python文档要好得多，但是就像许多计算机语言手册一样，也会受到技术术语的影响。 （这些术语或

关于它们的段落通常是为了取悦作者

自己）。


这是一个典型的写作方向是Mathematica手册，由

Stephen Wolfram完成。任何聪明的外行人都没有计算机科学学位

可以直接阅读，并且不受阻碍地学习一种语言，就像lisp语言的功能一样。这样的文件根本不是很难写的。 （与计算机科学家或IT权威人士中的许多人相反。）所需要的只是上面概述的一些简单的

原则。

Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

i''ve started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

quick example:
If the input string is too long, they don''t truncate it, but return it
unchanged; this will mess up your column lay-out but that''s usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
"x.ljust( n)[:n]".

better:
If the input string is too long, they don''t truncate it, but return it
unchanged;
-----------------
delete: Reverse quotes (``) are equivalent to repr(), but their use is
discouraged.
-----------------
similarly, many places mentioning uncritical info such as warning or
reference to other languages should be deleted.

the tutorial should be simple, concise, to the point, stand along.
Perhaps 1/5th length of the tutorial should be deleted for better.
Follow the above principles.

at places often a whole paragraph on some so called computer science
jargons should be deleted. They are there more to showcase inane
technicality than do help the reader. (related, many passages with
jargons should be rewritten sans inane jargon. e.g. mutable object.)

one easy way to understand these principles is to compare perl''s
documentation or unix man pages to Python''s. The formers are often
irrelevant, rambling on, not stand-along (it is written such that it
unnecessarily requires the reader to be knowledgable of lots of other
things). Python docs are much better, but like many computer language
manuals, also suffers from verbiage of tech jargons. (these jargons or
passages about them are usually there to please the authors
themselves).

A exemplary writing in this direction is the Mathematica manual by
Stephen Wolfram. Any intelligent layman sans computer science degree
can read it straightforwardly, and learn unhindered a language that is
tantamount to features of lisp languages. Such documentation is not
difficult to write at all. (contrary to the lot of "computer
scientists" or IT pundits morons.) All it take is some simple
principles outlined above.
Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

推荐答案

Xah Lee写道：

Xah Lee wrote:

我最近开始阅读python教程。
http://python.org/doc/2.3.4/tut/tut.html

最后！这是关于时间......

这里有一些快速批评：

i''ve started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html
Finally! It was about time...
Here are some quick critique:

鉴于你似乎对自己的批评完全不敏感 - 例如你的

继续发布无用的语言比较，以及

帖子的帖子要求停止并限制你自己到你的邮件列表 - 我

怀疑你会得到很多关注。


-

问候，


Diez B. Roggisch

Given that you seem to be totally inert to critique yourself - e.g. your
continued posting of useless language comparison, and the plethorea of
posts requesting to stop that and limit yourself to your mailing list - I
doubt you''ll get much attention for that.

--
Regards,

Diez B. Roggisch

你不应该提供这样的建议！ （和交叉路口... WTF？）。


我一直在努力跟随你的perl / python雅虎集团，但是

你的帖子很糟糕。


也许你应该提供你发布的代码的输出。然后我会实际知道我想要实现的目标。因为它是我必须将你的代码剪切/粘贴到解释器中以解决它的作用。


这与Lisp有什么关系？ （我在cll）。


drewc


Xah Lee写道：

You should not be giving such advice! (and the crosspost ... WTF?).

I''ve been trying to follow along with your perl/python yahoo group, but
your posts are terrible.

Perhaps you should provide the output of the code you post. Then i''d
actually know what i''m trying to achieve. As it is i have to cut/paste
your code into an interpreter just to figure out what it does.

What does this have to do with Lisp? (i''m in c.l.l).

drewc

Xah Lee wrote:

我已经最近开始阅读python教程。
http：/ /python.org/doc/2.3.4/tut/tut.html

以下是一些快速评论：

快速示例：
如果输入字符串太长，它们不会截断它，但返回它不变;这会弄乱你的列布局，但这通常比替代方案更好，这可能是一个值。 （如果你真的想要截断，你可以随时添加切片操作，如
x.ljust（n）[：n]中那样。

更好：
如果输入字符串太长，它们不会截断它，但返回它
不变;
----------------- <删除：反向引号（``）等同于repr（），但不建议使用它们。
----------------- <类似地，很多地方都应该删除一些不加批判的信息，例如警告或
引用其他语言。

这个教程应该简单，简洁，重点突出。或许应该删除教程的1/5长度以便更好。
遵循上述原则。

在某些地方经常会有一段所谓的计算机科学
应该删除这些术语。他们有更多的东西来展示无聊的技术性而不是帮助读者。（相关的，许多带有
术语的段落应该改写为无用的行话。例如可变对象。）

理解这些原则的一个简单方法是将perl的
文档或unix手册页与Python的文档进行比较。前者通常是无关紧要的，漫无目的，而不是一直存在（它的写作使得它不必要地让读者知道许多其他的东西）。 Python文档要好得多，但是像许多计算机语言手册一样，也会受到技术术语的误解。 （关于它们的这些术语或
段落通常是为了取悦作者本身）。

这方面的示范性写作是由Stephen Wolfram撰写的Mathematica手册。任何聪明的外行人都没有计算机科学学位可以直接阅读，并且学习不受阻碍的语言等同于lisp语言的功能。这样的文件根本不难写。 （与计算机科学家或IT专家蠢货相反。）所有这些都是上面概述的一些简单的原则。
Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

i''ve started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

quick example:
If the input string is too long, they don''t truncate it, but return it
unchanged; this will mess up your column lay-out but that''s usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
"x.ljust( n)[:n]".

better:
If the input string is too long, they don''t truncate it, but return it
unchanged;
-----------------
delete: Reverse quotes (``) are equivalent to repr(), but their use is
discouraged.
-----------------
similarly, many places mentioning uncritical info such as warning or
reference to other languages should be deleted.

the tutorial should be simple, concise, to the point, stand along.
Perhaps 1/5th length of the tutorial should be deleted for better.
Follow the above principles.

at places often a whole paragraph on some so called computer science
jargons should be deleted. They are there more to showcase inane
technicality than do help the reader. (related, many passages with
jargons should be rewritten sans inane jargon. e.g. mutable object.)

one easy way to understand these principles is to compare perl''s
documentation or unix man pages to Python''s. The formers are often
irrelevant, rambling on, not stand-along (it is written such that it
unnecessarily requires the reader to be knowledgable of lots of other
things). Python docs are much better, but like many computer language
manuals, also suffers from verbiage of tech jargons. (these jargons or
passages about them are usually there to please the authors
themselves).

A exemplary writing in this direction is the Mathematica manual by
Stephen Wolfram. Any intelligent layman sans computer science degree
can read it straightforwardly, and learn unhindered a language that is
tantamount to features of lisp languages. Such documentation is not
difficult to write at all. (contrary to the lot of "computer
scientists" or IT pundits morons.) All it take is some simple
principles outlined above.
Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

>>>>> " Xah" == Xah Lee< xa*@xahlee.org>写道：


Xah>在一些所谓的电脑上经常整个段落

Xah>科学术语应该删除。他们还有更多的东西

Xah>展示inane技术性比帮助

Xah>读者。 （相关的，许多带有术语的段落应该是

Xah>重写sans inane jargon。例如可变对象。）


可变对象的概念非常重要python，和

理解是回答两个反复出现的新手问题的关键


*为什么列表或词典不能成为词典的关键？


*为什么在

a函数定义中使用列表作为关键字参数的默认值通常会导致意外结果？


所以它绝对是教程中适当的材料。


至于行话，很难说对象在
python中是无聊的行话。事实上，新式类的基类确实是

" object"，如果你想自己写一个这样的类，你需要做b $ b需要做的事情''类MyClass（对象）''。因此，对象不是一种无用的行话，而是一种面向对象的编程语言。你还和我在一起吗？


好​​的，现在变成了可变的。可变的意思是多变的，虽然它比一个不起眼的词更可取，但它确实更容易滚动

的舌头。对于一些读者来说，也许可变对象可能更容易获得，但它并没有流动。所以

python教程也许应该在引入它时定义mutable。

它有点暗示;在字符串的上下文中，第一次在

文档中提到了mutable


与不可变的字符串不同，可以更改

列表中的各个元素：

现在我最近在一个新主题上思考如何撰写批评：

它更多建设性地为文档建议新文本

而不是将其标记为亵渎。


JDH

>>>>> "Xah" == Xah Lee <xa*@xahlee.org> writes:

Xah> at places often a whole paragraph on some so called computer
Xah> science jargons should be deleted. They are there more to
Xah> showcase inane technicality than do help the
Xah> reader. (related, many passages with jargons should be
Xah> rewritten sans inane jargon. e.g. mutable object.)

The concept of mutable objects is extremely important in python, and
understanding is the key to answering two recurring newbie questions

* Why can''t lists or dictionaries be keys to dictionaries?

* Why does using a list as a default value for a keyword argument in
a function definition often lead to unexpected results?

So it is definitely appropriate material in a tutorial.

As for jargon, it is hard to argue that "object" is inane jargon in
python. In fact, the base class for new-styled classes is indeed
"object", and if you want to write one of these classes yourself, you
need to do ''class MyClass(object)''. So object is not inane jargon in
an object oriented programming language. You still with me?

OK, now on to mutable. mutable means changeable, albeit it''s a little
more of an obscure word than changeable, but it does roll off the
tongue a bit more easily. Perhaps ''changeable object'' would be more
accessible to some readers, but it doesn''t flow as well. So the
python tutorial should perhaps define mutable when it introduces it.
Which it does somewhat implicitly; the first time mutable is mentioned in the
docs, in the context of strings

Unlike strings, which are immutable, it is possible to change
individual elements of a list:
And now for my last musing on a new topic "How to write a critique":
It is much more constructive to suggest new text for documentation
than to brand it inane.

JDH

这篇关于如何编写教程的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！