文档建议 [英] Documentation suggestions
问题描述
以下是关于重组Python文档的一些想法，
一个很大的建议。
这个教程看起来状态很好，因为Raymond
Hettinger一直保持最新状态。它没有涵盖
一切，但它是一个坚实的介绍，如果人们没有找到
为他们工作，他们有很多选择图书。没有建议
这里。
库参考中有无穷无尽的小错误，但这似乎是不可避免的
。它记录了许多不同的和不断变化的模块，并且
要记录的内容本身就是一个有争议的问题，所以我不认为
小问题流将永远停止。
LibRef中还有另一个难题：它是参考还是
教程？它是否按字母顺序列出方法，以便您可以查看它们，或者它是否以教学上有用的顺序列出它们？我认为它必须是一个参考;
如果每个部分都是一个教程，
手册将是巨大的。在这里，我认为解决方案是鼓励
单独的教程和HOWTO，并从LibRef链接到它们。
库引用有如此多的模块，目录
非常大。再说一次，这不是我们能解决的问题;拆分
它分成单独的手册似乎不会有帮助。
扩展/嵌入手册不是很好，但只有高级用户
会接触到它，所以我不认为这是一个关键因素。
（Michael Hudson的新手册是一个很有前途的替代品。）
我怀疑文档的致命弱点是语言参考。
撇开它不是最新的事实与新式课程和其他东西;
其他的东西;这可以通过一些努力来解决。
在某种程度上，指南试图非常正式;它写的是
就像一个实现者的规范，而不是人们将会读取的文件。但是人们没有别的办法可以学习所有特殊对象方法，比如__add__;本教程不能完全覆盖它们，并且LibRef并没有描述它们。所以新手
被卡住了。
例如，我注意到Tim Bray的博客中的这个传递参考：
http://www.tbray.org/ongoing/When/ 200x / 2005/08/27 / Ruby
基于第一印象和曝光率（
很重要的基础）Ruby似乎更好地记录并且比Python更容易获得
。我实际上是用Python写的（一点点）
生产代码，但我总觉得
有很多东西在进行我没有了解; a / b
几天后，我想我已经更好地掌握了什么
Ruby'，即使在我不看的地方。
我不知道Bray究竟是什么意思，但怀疑更具可读性的b $ b参考指南可以帮助他了解发生了什么。
也许我们需要一个更友好的RefGuide对应物，
就像Bezley开头的20页Python介绍一样
基本参考：
*逐个查看语句
*了解基本类型及其方法
*翻阅对象语义
*涵盖了RefGuide第2章中的一些词汇材料
*首要原则：详细介绍一下，但是/>
不是每个角落的情况;使文字可读，而不是一丝不苟
精确。
（我应该指出：这个建议并不完全不同于
X * h L **的一些建议。他（？）以有毒的方式提出他的
建议，并用他自己的古怪
术语，但这并不意味着他总是错的，例如他关于re模块的文档的b
投诉很好地放在了
main中。）
如此友好的文件存在一个问题：如果我们总是更新友好文件，它可能会使Ref Guide
更加无关紧要
（这很容易）并让RefGuide进一步离开
日期（因为它很难更新）。我不知道这是不是因为没有友好的指导，或者完全倾销RefGuide
的话。
倾倒RefGuide意味着Python的语义没有更正式的描述
。我不知道这是否重要。理论上，Jython或IronPython的实现者可能会使用RefGuide来知道他们需要实现什么，但实际上我怀疑是
实现者使用测试套件和现有库作为检查。也许
我们真的不需要对Python进行繁琐精确的描述。
人们怎么想？
--amk
Here are some thoughts on reorganizing Python''s documentation, with
one big suggestion.
The tutorial seems to be in pretty good shape because Raymond
Hettinger has been keeping it up to date. It doesn''t cover
everything, but it''s a solid introduction, and if people don''t find it
works for them, they have lots of alternative books. No suggestions
here.
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don''t think the
stream of small problems will ever cease.
There''s another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge. Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.
The library reference has so many modules that the table of contents
is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn''t seem like it would help.
The Extending/Embedding manual isn''t great, but only advanced users
will come in contact with it, so I don''t think it''s a critical factor.
(Michael Hudson''s new manual is a promising replacement.)
I suspect the Achilles'' heel of the docs is the Language Reference.
Put aside the fact that it''s not up to date with new-style classes and
other stuff; that would be fixable with some effort.
To some degree, the guide is trying to be very formal; it''s written
like a specification for an implementor, not a document that people
would read through. But there''s no other way for people to learn
about all the special object methods like __add__; the tutorial can''t
cover them all, and the LibRef doesn''t describe them. So the newbie
is stuck.
For example, I noticed this passing reference in Tim Bray''s weblog:
http://www.tbray.org/ongoing/When/200x/2005/08/27/Ruby
Based on first impressions and light exposure (a basis that
matters a lot) Ruby seems better-documented and easier to get
into than Python. I''ve actually written (a little)
production code in Python, but I always had the feeling that
there was lots of stuff going on I didn''t understand; a
couple of days in, I think I have a better grasp on what
Ruby''s up to, even where I''m not looking.
I don''t know exactly what Bray meant, but suspect that a more readable
reference guide would have helped him understand what was going on.
Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley''s
Essential Reference:
* go over the statements one-by-one
* go over the basic types and their methods
* go over object semantics
* cover some of the lexical material in chapter 2 of the RefGuide
* overarching principles: go into a fair bit of detail, but
not every corner case; make the text readable, not meticulously
precise.
(I should point out: this suggestion is not entirely different from
some of the suggestions that X*h L** has made. He (?) makes his
suggestions in a venomous style, and with his own eccentric
terminology, but that doesn''t mean he''s always wrong, e.g. his
complaints about the re module''s documentation are well-placed in the
main.)
One problem with such a friendly document: it might make the Ref Guide
even more irrelevant, if we always updated the friendly document
(which is easy) and left the RefGuide to drift even further out of
date (because it''s hard to update). I don''t know if this is an
argument for not having a friendly guide, or for dumping the RefGuide
entirely.
Dumping the RefGuide means there isn''t a more formal-style description
of Python''s semantics. I don''t know if this matters. In theory, the
implementors of Jython or IronPython could be using the RefGuide to
know what they need to implement, but in practice I suspect
implementors use the test suite and existing library as checks. Maybe
we don''t really need a tediously precise description of Python.
What do people think?
--amk
推荐答案
AM Kuchling写道：
A.M. Kuchling wrote:
这个教程看起来状态很好，因为Raymond
Hettinger一直在保持它的最新状态。它没有涵盖所有内容，但它是一个坚实的介绍，如果人们找不到它
为他们工作，他们有很多替代书籍。没有建议
这里。
我最后一次查看它时，我认为教程是文档中最薄弱的部分，因为它假设你是在Python上/>
来自另一种语言，并且通常认为语言是C.我的意思是，
第一行说，如果你曾经写过一个大的shell脚本...... br />
大多数人都没有。第二页假设您使用的是Unix
并在Windows中作为事后的想法抛出。第三页使用术语就像在C中一样来演示
字符串文字。这是一个没有意义的，因为任何熟悉C的人都可能足够聪明
来为自己建立连接，而且任何人都不会这样做
欣赏正在解释的内容。这种主题在整个过程中继续
。
曾几何时我希望几乎所有Python程序员都来自C，
但是今天，我怀疑这是真的，特别是因为大多数大学似乎更喜欢用Java而不是C ++来教授Java。简而言之，对于今天的潜在Python程序员来说，这个教程已经过时了。门票：我曾经提供过
来帮助清理它，但当我得到
做*的回复时*@python.org ，我开始了一份新工作，不再有时间。对不起。
至于替代书籍评论，我认为这是非常错误的...
人们肯定更有可能购买全面的参考书一个很好的教程，他们已经迷上了他们的b $ b语言。
为他们不太了解的语言购买入门级文本但
似乎有很好的参考资料！
库参考中有无穷无尽的小错误，但这似乎是不可避免的。它记录了许多不同的和不断变化的模块，并且要记录什么本身就是一个有争议的问题，所以我不认为小问题的流会永远停止。
制作像PHP'文档这样的文档。用户可以在文档中发布附录和更正
，然后所有其中一位官方维护人员必须在稍后的修正中弃用。
LibRef中还有另一场斗争：它是一个参考还是一个
教程？它是按字母顺序列出方法，以便您可以查看它们，还是以教学上有用的顺序列出它们？我认为它必须是一个参考;如果每个部分都是一个教程，
手册将是巨大的。
我同意：最重要的参考。但是，除了最琐碎的
库之外，其他所有库都应该有一个简短的例子，最好是在他们的文档的第一页
，这样你就可以快速了解这是否
您希望它做什么，以及代码的外观。有些
库不是（ConfigParser浮现在脑海中，Threading是另一个）
这使得开始使用它们有点苦差事。同样，如果web
用户可以像PHP一样提供文档评论示例，
以后可以添加它们。
图书馆参考有这么多模块，目录
非常大。再说一次，这不是我们能解决的问题;将它分成单独的手册似乎没什么用。
The tutorial seems to be in pretty good shape because Raymond
Hettinger has been keeping it up to date. It doesn''t cover
everything, but it''s a solid introduction, and if people don''t find it
works for them, they have lots of alternative books. No suggestions
here.
The last time I looked at it, I thought the tutorial was the weakest
part of the documentation, because it assumed you were coming at Python
from another language, and often assumed that language was C. I mean,
the very first line says, "If you ever wrote a large shell script"...
which most people never have. The second page assumes you''re using Unix
and throws in Windows as an afterthought. The third page demonstrates
string literals using the term "just as you would do in C". This is a
bit pointless because anyone familiar with C is probably bright enough
to make the connection for themselves, and anyone who isn''t will not
appreciate what is being explained. This sort of theme continues
throughout.
Once upon a time I expect nearly all Python programmers came from C,
but today, I doubt that is true, especially since most universities
seem to prefer teaching Java over C++. In short, the tutorial is quite
outdated for today''s prospective Python programmers. Admission: I once
offered to help clean it up, but by the time I got a reply from
do**@python.org, I had started a new job and no longer had time. Sorry.
As for the alternative books comment, I think this is very wrong...
people are surely far more likely to buy a comprehensive reference to a
language they''re already hooked on by a good tutorial, than they are to
buy an entry-level text for a language they don''t quite understand but
which seems to boast good reference material!
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don''t think the
stream of small problems will ever cease.
Make the docs like PHP''s docs. Users can post addendums and corrections
to the documentation, then all one of the official maintainers has to
do is fold in those corrections later.
There''s another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge.
I agree: reference foremost. However, all but the most trivial
libraries should have a short example, preferably on the first page of
their docs, so that you can quickly get an idea of whether this does
what you want it to do, and how the code is going to look. Some
libraries don''t (ConfigParser comes to mind, Threading is another)
which make using them a bit of a chore to begin with. Again, if web
users could contribute examples as comments on the docs as with PHP,
they can be added in later.
The library reference has so many modules that the table of contents
is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn''t seem like it would help.
我个人很高兴看到很多这些模块从
发行版中删除，但我希望很少有人同意我的看法。 ;）
-
Ben Sizer
Personally I''d be happy to see a lot of those modules removed from the
distribution, but I expect few will agree with me. ;)
--
Ben Sizer
A.M。 Kuchling写道：
A.M. Kuchling wrote:
以下是关于重组Python文档的一些想法，其中有一个很重要的建议。
感谢你提出这个问题...
库参考中有无穷无尽的小错误，但这似乎是不可避免的。它记录了许多不同的和不断变化的模块，并且要记录什么本身就是一个有争议的问题，所以我不认为小问题的流会永远停止。
由于php.net风格的评论主题经常出现，我以为我会这么说b $ b请注意我一直在评论系统：
http://pythonpaste.org/comment/commentary/ - 这对于
收集和管理文档的小更新和修复可能很有用。
LibRef中还有另一个问题：它是引用还是
教程？它是按字母顺序列出方法，以便您可以查看它们，还是以教学上有用的顺序列出它们？我认为它必须是一个参考;如果每个部分都是一个教程，
手册将是巨大的。在这里，我认为解决方案是鼓励单独的教程和HOWTO，并从LibRef链接到它们。
我们没有明确的地方放置这些材料。人们的个人
页面留下了材料消失的可能性，而且因为那个
的东西通常没有明确的许可证，我们不一定能肯定
如果原件消失或者超出
日期，我们可以将它移到别处。 Wiki可能会起作用，也许我们应该只说Wiki上的
贡献是教程的首选形式和
howtos。然后，当然，我们必须链接到它们。评论
系统可以更有机地发生。
库引用有很多模块，目录
非常大。再说一次，这不是我们能解决的问题;把它拆分成单独的手册并不像它会有所帮助。
那里有很多愚蠢的模块。如果有一个模块
索引排除了无用的模块，我会很高兴。比如说，
MimeWriter或flp。我认为按字母顺序排序或分类并不重要，而只是一个较短的列表。或者可能是分类，但
布局，以便它仍然适用于一个屏幕;主库ToC
太长了，因为它不适合屏幕，但
类别仍然有用。
我怀疑阿基里斯的文件后跟是语言参考。
撇开这样一个事实，即它不是最新的课程和其他东西;这可以通过一些努力来解决。
在某种程度上，指南试图非常正式;它的编写类似于实现者的规范，而不是人们将阅读的文档。但是人们没有其他方法可以学习所有特殊对象方法，如__add__;教程不能覆盖所有这些，而LibRef并没有描述它们。所以新手
被卡住了。
绝对可以;对于新手而言，存在一个问题，即语言。
记录了一个地方（并且很难找到），标准库
在其他地方。作为一个新手，很难知道哪个是哪个。
此外，像内置函数这样的功能特别难以找到恕我直言。我现在经常使用pydoc来做这些事情，但不是因为我特别想要我们的b $ b。
也许我们需要一个更友好的RefGuide对应的东西
喜欢在Beazley的开头，20页的Python介绍
基本参考：
*逐个翻阅语句
*了解基本类型和他们的方法
*翻阅对象语义
*涵盖RefGuide第2章中的一些词汇材料
*总体原则：详细介绍一下，但不是每个角落的情况;使文字可读，而不是精心准确。
我认为基于示例的参考可能比
当前布局更有用。角落*是重要的，并且
能够阅读文档以完全理解一个特定的
功能是有价值的。比方说，例如（现在已经被曝光）。
但是通过一系列例子可以更容易理解那些用于证明行为的
，而不是一个正式的描述。
这样一个友好的文件有一个问题：如果我们总是更新友好的文件，这可能会使Ref指南更加无关紧要（这很容易）并使RefGuide离开日期更远（因为它很难更新）。我不知道这是否是一个没有友好指南的论据，或者完全倾倒RefGuide
倾倒RefGuide意味着没有Python的语义更正式的描述。我不知道这是否重要。理论上，Jython或IronPython的实现者可能正在使用RefGuide知道他们需要实现什么，但实际上我怀疑实现者使用测试套件和现有库作为检查。也许
我们真的不需要对Python进行繁琐精确的描述。
Here are some thoughts on reorganizing Python''s documentation, with
one big suggestion.
Thanks for bringing this up...
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don''t think the
stream of small problems will ever cease.
Since the topic of php.net-style comments comes up often, I thought I''d
note I''ve been working on a comment system:
http://pythonpaste.org/comment/commentary/ -- this might be useful for
collecting and managing small updates and fixes to the documentation.
There''s another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge. Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.
We don''t have a clear place to put that material. People''s personal
pages leave the potential for material disappearing, and since that
stuff usually doesn''t have a clear license we can''t necessarily be sure
we can move it elsewhere if the original disappears or becomes out of
date. The Wiki would probably work, and maybe we should just say that
contributions on the Wiki are the preferred form for tutorials and
howtos. Then, of course, we have to link to them. With a commenting
system that can happen more organically.
The library reference has so many modules that the table of contents
is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn''t seem like it would help.
There''s a lot of dumb modules in there. I''d love if there was a module
index that excluded modules that were not useful. Like, say,
MimeWriter or flp. I think alphabetical or categorized doesn''t matter
that much, compared to just a shorter list. Or maybe categorized, but
layed out so that it still all fits on one screen; the main library ToC
is simply too long because it doesn''t fit on a screen, but the
categories can still be useful.
I suspect the Achilles'' heel of the docs is the Language Reference.
Put aside the fact that it''s not up to date with new-style classes and
other stuff; that would be fixable with some effort.
To some degree, the guide is trying to be very formal; it''s written
like a specification for an implementor, not a document that people
would read through. But there''s no other way for people to learn
about all the special object methods like __add__; the tutorial can''t
cover them all, and the LibRef doesn''t describe them. So the newbie
is stuck.
Definitely; there''s a problem for a newcomer, where the "language" is
documented one place (and hard to find), and the standard library
someplace else. As a newcomer it can be hard to know which is which.
Also, things like the functions in builtins are particularly hard to
find IMHO. I usually use pydoc for these things now, but not because I
particularly want to.
Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley''s
Essential Reference:
* go over the statements one-by-one
* go over the basic types and their methods
* go over object semantics
* cover some of the lexical material in chapter 2 of the RefGuide
* overarching principles: go into a fair bit of detail, but
not every corner case; make the text readable, not meticulously
precise.
I think that an example-based reference could be more useful than the
current layout. The corner cases *are* important, and it''s valuable to
be able to read documentation to fully understand one particular
feature. Like, say, exceptions (which are undercovered right now).
But it can be easier to understand those with a series of examples
meant to demonstrate the behavior, than with a formal description.
One problem with such a friendly document: it might make the Ref Guide
even more irrelevant, if we always updated the friendly document
(which is easy) and left the RefGuide to drift even further out of
date (because it''s hard to update). I don''t know if this is an
argument for not having a friendly guide, or for dumping the RefGuide
entirely.
Dumping the RefGuide means there isn''t a more formal-style description
of Python''s semantics. I don''t know if this matters. In theory, the
implementors of Jython or IronPython could be using the RefGuide to
know what they need to implement, but in practice I suspect
implementors use the test suite and existing library as checks. Maybe
we don''t really need a tediously precise description of Python.
对于实现者而言，测试套件似乎比任何指南都更有用，
特别是在没有完全确保该指南的准确性的情况下。
一系列例子似乎比正式描述更具体，并且
因此可以不仅仅是更有帮助，而且更准确的是如何传递知识
。
A test suite seems far more useful to implementors than any guide,
especially where the accuracy of that guide is not completely assured.
A series of examples seems more concrete than a formal description, and
as such can be not just more helpful, but also a more accurate in how
it transfers knowledge.
Ian Bicking写道：
Ian Bicking wrote:
库引用中有无穷无尽的小错误，但这似乎是不可避免的。它记录了许多不同的和不断变化的模块，并且要记录什么本身就是一个有争议的问题，所以我不认为小问题的流会永远停止。
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don''t think the
stream of small problems will ever cease.
由于php.net风格的评论主题经常出现，我想我会注意到我一直在研究评论系统：
http://pythonpaste.org/comment/commentary/ - 这可能对
有用收集和管理文档的小更新和修复。
Since the topic of php.net-style comments comes up often, I thought I''d
note I''ve been working on a comment system:
http://pythonpaste.org/comment/commentary/ -- this might be useful for
collecting and managing small updates and fixes to the documentation.
是的，按照php的文档完成的方式，Xah Lee最近的巨魔
。
Yes, do it the way php''s documentation is done, Xah Lee''s recent trolls
aside.
这篇关于文档建议的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
