Xah的Edu角落：质量技术写作的例子 [英] Xah's Edu Corner: Examples of Quality Technical Writing
问题描述
我很高兴今天阅读PHP的手册。
http://www.php.net/manual/en/
虽然漂亮的主页是unix血统的另一个犯罪黑客，
但是如果我们来判断其文档的质量，那就是
无可挑剔。
它拥有或拥有属性的：
a？¢重要而有用。
PHP源于mundaness，如Perl和Apache。它的doc是实用性导向的文件并不令人惊讶，Perl和
Apache的文档也是如此。
a？¢极其清晰！
该文档编写得非常好。作者的写作技巧
表明，他们可以清楚地表达自己的想法，并且他们已经将想法放入他们想说的内容中。
a？¢充足的用法示例。
与Perl的文档一样，PHP文档不怕显示示例片段，
但是没有滥用它，好像只是简单地用例子来代替正确的b $ b规范或讨论。
a？¢适当的功能或关键词是相互关联的。
这方面在其他高质量的文档中也做得很好，比如
Mathematica，Java，MS JScript，Perl的官方文档。
a？¢没有滥用行话。
事实上，它的写得非常好，其中几乎没有任何术语/>
docs，但将其意图传达给了一个发球台。这方面也可以在Mathematica的文档中看到
，或者以微软的JScript文档为例。
a？¢没有作者自慰。 （事实上，你不会看到第一人称的b $ b视角，就像大多数高质量的科技写作一样。）
我们必须真的感谢PHP文档的作者。因为，PHP，unix shit文化中的免费狗屎，与Perl的极端关系以及
Apache（两者都有极其母版的文档），但可以断续
本身来自一个糟糕的环境，并且保持纯净和干净，成为一个典范
的技术写作。
----- -------
为了这篇文章的目的提醒：
世界上的母亲是社区和文学作家： Unix
（手册页），Perl，Apache，Python。
正如我之前提到或阐述的那样，unix&阿帕奇在犯罪方面是最糟糕的，Perl是一个紧密的跟进。 Python在它的一个类别上是b
拥有，是一个变异的计算机技能他妈的，甚至可能比Perl的doc更糟糕了。
。 />
这里有各种质量技术着作的样本列表：
a？¢Mathematica
http://documents.wolfram.com/mathematica/
a？¢微软的JScript官方文档
http://msdn.microsoft.com/library/en...ndamentals.asp
a？¢Emacs Lisp简介（作者：Robert J. Chassell）
http://www.gnu.org/software / emacs / emacs-lisp-intro /
（GNU项目的文档几乎总是高质量的文档。
for exa mple，正式的emacs和elisp docs都具有很高的质量。）
a？¢Java官方文件
http://java.sun.com/j2se/1.4.2/ docs / api / index.html
Java，是一种瓶装灵活的语言，有着不间断的谎言
备份大量的金钱$，然而聘请了专业的
作家的巨大官方文件？为一种非常复杂的语言制作了一个非常好的完美文档。 （然而，官方Java
教程是一个他妈的垃圾）
a？¢方案（R5RS）
http：//www.schemers.org/Documents/St ... 5rs-ZH-2.html
a？¢计划（在Fixnum Days自学课程）
http://www.ccs.neu.edu/home/dorai/ t -... eme-ZH-1.html
这些都是高质量的技术着作。他们有不同的风格
以及观众和报道。如果你想看清晰和简洁，请参阅JScript，PHP和Scheme简介。如果你想看到
详细程度的清晰度，请参阅Emacs Lisp Intro。为了清楚起见，sans arcana尚未涵盖
esoterica，请参阅Mathematica文档。其中一些是为没有编程经验的人写的，但其功能相当于
教学/记录非常先进的编程概念。如果您希望在IT专业级别上看到正确使用jargons，请参阅
Java文档。如果你想看到学术上的模范科技写作
风格，请参阅Scheme R5RS。
相关论文：
为什么OpenSource文档质量低劣
http://xahlee.org/ UnixResource_dir / w ... bni_papri.html
Xah
xa * @ xahlee。组织
a ?? http://xahlee.org/
i had the pleasure to read the PHP''s manual today.
http://www.php.net/manual/en/
although Pretty Home Page is another criminal hack of the unix lineage,
but if we are here to judge the quality of its documentation, it is a
impeccability.
it has or possesses properties of:
a?￠ To the point and useful.
PHP has its roots in mundaness, like Perl and Apache. Its doc being
practicality oriented isn''t a surprise, as are the docs of Perl and
Apache.
a?￠ Extreme clarity!
The doc is extremely well-written. The authors''s writing skills
shows, that they can present their ideas clearly, and also that they
have put thoughts into what they wanted to say.
a?￠ Ample usage examples.
As with Perl''s doc, PHP doc is not afraid to show example snippets,
yet not abuse it as if simply slapping on examples in lieu of proper
spec or discussion.
a?￠ Appropriate functions or keywords are interlinked.
This aspect is also well done in other quality docs, such as
Mathematica, Java, MS JScript, Perl''s official docs.
a?￠ No abuse of jargons.
In fact, it''s so well written that there''s almost no jargons in its
docs, yet conveys its intentions to a tee. This aspect can also be seen
in Mathematica''s doc, or Microsoft''s JScript doc, for examples.
a?￠ No author masturbation. (if fact, you won''t see a first-person
perspective, as is the case with most quality tech writing.)
We must truely appreciate the authors of the PHP doc. Because, PHP, as
a free shit in the unix shit culture, with extreme ties to Perl and
Apache (both of which has extremely motherfucked docs), but can wean
itself from a shit milieu and stand pure and clean to become a paragon
of technical writing.
------------
Reminder for the purpose of this post:
The world''s mother fuckers are the community and doc writers of: Unix
(man pages), Perl, Apache, Python.
As i have alluded or expounded before, the unix & Apache are criminally
the worst, Perl being a close follow up. Python''s on a class of its
own, being a mutated Computer Sciency fuck that is possibly even worse
on the whole than Perl''s doc.
Here a sample list of a variety of quality technical writings:
a?￠ Mathematica
http://documents.wolfram.com/mathematica/
a?￠ Microsoft''s JScript official docs
http://msdn.microsoft.com/library/en...ndamentals.asp
a?￠ Emacs Lisp Introduction (by Robert J. Chassell)
http://www.gnu.org/software/emacs/emacs-lisp-intro/
(GNU project''s documentations are almost always quality documentations.
For example, the official emacs and elisp docs ale both of high
quality.)
a?￠ Java official doc
http://java.sun.com/j2se/1.4.2/docs/api/index.html
Java, being a bottled-up inflexible language with incessant lies
backup by huge amounts of $money$, nevertheless hired professional
writers for its huge official documentation a?? produced a very well
done doc for a very complex language. (however, the official Java
Tutorial is a fucking crap)
a?￠ Scheme (R5RS)
http://www.schemers.org/Documents/St...5rs-Z-H-2.html
a?￠ Scheme (Teaching yourself Scheme in Fixnum Days)
http://www.ccs.neu.edu/home/dorai/t-...eme-Z-H-1.html
These are all quality technical writings. They have different styles
and audiences and coverages. If you want to see clarity and concision,
see JScript, PHP, and Scheme intro. If you want to see clarity with
verbosity, see Emacs Lisp Intro. For clarity sans arcana yet covers
esoterica, see the Mathematica doc. Some of these are written for
people with no experience in programing, yet functions as equivalent to
teaching/documenting extremely advanced programing concepts. If you
want to see proper use of jargons at a IT professional level, see the
Java doc. If you want to see exemplary tech writing in a academic
style, see the Scheme R5RS.
Related essay:
Why OpenSource Documentation is of Low Quality
http://xahlee.org/UnixResource_dir/w...bni_papri.html
Xah
xa*@xahlee.org
a?? http://xahlee.org/
推荐答案
money
，然而聘请了专业的
作家的巨大官方文件a ??为一种非常复杂的语言制作了一个非常好的完美文档。 （然而，官方Java
教程是一个他妈的垃圾）
a？¢方案（R5RS）
http：//www.schemers.org/Documents/St ... 5rs-ZH-2.html
a？¢计划（在Fixnum Days自学课程）
http://www.ccs.neu.edu/home/dorai/ t -... eme-ZH-1.html
这些都是高质量的技术着作。他们有不同的风格
以及观众和报道。如果你想看清晰和简洁，请参阅JScript，PHP和Scheme简介。如果你想看到
详细程度的清晰度，请参阅Emacs Lisp Intro。为了清楚起见，sans arcana尚未涵盖
esoterica，请参阅Mathematica文档。其中一些是为没有编程经验的人写的，但其功能相当于
教学/记录非常先进的编程概念。如果您希望在IT专业级别上看到正确使用jargons，请参阅
Java文档。如果你想看到学术上的模范科技写作
风格，请参阅Scheme R5RS。
相关论文：
为什么OpenSource文档质量低劣
http://xahlee.org/ UnixResource_dir / w ... bni_papri.html
Xah
xa * @ xahlee。组织
a ?? http://xahlee.org/
, nevertheless hired professional
writers for its huge official documentation a?? produced a very well
done doc for a very complex language. (however, the official Java
Tutorial is a fucking crap)
a?￠ Scheme (R5RS)
http://www.schemers.org/Documents/St...5rs-Z-H-2.html
a?￠ Scheme (Teaching yourself Scheme in Fixnum Days)
http://www.ccs.neu.edu/home/dorai/t-...eme-Z-H-1.html
These are all quality technical writings. They have different styles
and audiences and coverages. If you want to see clarity and concision,
see JScript, PHP, and Scheme intro. If you want to see clarity with
verbosity, see Emacs Lisp Intro. For clarity sans arcana yet covers
esoterica, see the Mathematica doc. Some of these are written for
people with no experience in programing, yet functions as equivalent to
teaching/documenting extremely advanced programing concepts. If you
want to see proper use of jargons at a IT professional level, see the
Java doc. If you want to see exemplary tech writing in a academic
style, see the Scheme R5RS.
Related essay:
Why OpenSource Documentation is of Low Quality
http://xahlee.org/UnixResource_dir/w...bni_papri.html
Xah
xa*@xahlee.org
a?? http://xahlee.org/
Xah Lee写道：
[...]
Xah Lee wrote:
[...]
a？¢没有作者自慰。 （事实上，你不会看到第一人称视角，就像大多数高质量的科技写作一样。）
我们[...]
a?￠ No author masturbation. (if fact, you won''t see a first-person
perspective, as is the case with most quality tech writing.)
We [...]
新读者请注意，这位作者因在许多不适当的网络上发布
煽动性和无关材料而闻名
新闻组。
-
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/
Will new readers please note that this author is well-known for posting
inflammatory and irrelevant material on many inappropriate network
newsgroups.
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/
这篇关于Xah的Edu角落：质量技术写作的例子的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
