如何编写教程

本文介绍了如何编写教程的处理方法，对大家解决问题具有一定的参考价值，需要的朋友们下面随着小编来一起学习吧！

问题描述

我最近开始阅读python教程。

以下是一些快速评论：

快速示例：

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

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

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

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

更好：

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

不变;

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

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

气馁。

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

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

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

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

遵循上述原则。

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

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

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

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

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

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

自己）。

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

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

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

原则。

Xah

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

principles

问题描述

推荐答案