Xah's Edu Corner: Examples of Quality Technical Writing

Discussion in 'Python' started by Xah Lee, Dec 6, 2005.

  1. Xah Lee

    Xah Lee Guest

    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:

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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 **** that is possibly even worse
    on the whole than Perl's doc.

    Here a sample list of a variety of quality technical writings:

    • Mathematica
    http://documents.wolfram.com/mathematica/

    • Microsoft's JScript official docs

    http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp


    • 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.)

    • 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 — produced a very well
    done doc for a very complex language. (however, the official Java
    Tutorial is a fucking crap)

    • Scheme (R5RS)
    http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-2.html

    • Scheme (Teaching yourself Scheme in Fixnum Days)
    http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-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/writ/gubni_papri.html

    Xah

    ∑ http://xahlee.org/
     
    Xah Lee, Dec 6, 2005
    #1
    1. Advertising

  2. Xah Lee

    Steve Holden Guest

    Xah Lee wrote:
    [...]
    > • No author masturbation. (if fact, you won't see a first-person
    > perspective, as is the case with most quality tech writing.)
    >
    > We [...]


    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/
     
    Steve Holden, Dec 6, 2005
    #2
    1. Advertising

  3. On 6 Dec 2005, at 04:55, Xah Lee wrote:

    > i had the pleasure to read the PHP's manual today.
    >
    > http://www.php.net/manual/en/


    To be fair, the PHP manual is pretty good most of the time. I mean,
    just imagine trying to use PHP *without* the manual?! It's not like
    the language is even vaguely consistent.
     
    Alex Stapleton, Dec 6, 2005
    #3
  4. "Xah Lee" <> writes:

    > 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:
    >
    > • 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.
    >
    > • Extreme clarity!


    Do you have an "Approved by Xah Lee" seal logo they could put on their web page?

    --
    __Pascal Bourguignon__ http://www.informatimago.com/

    "Remember, Information is not knowledge; Knowledge is not Wisdom;
    Wisdom is not truth; Truth is not beauty; Beauty is not love;
    Love is not music; Music is the best." -- Frank Zappa
     
    Pascal Bourguignon, Dec 6, 2005
    #4
  5. Pascal Bourguignon wrote:
    > Do you have an "Approved by Xah Lee" seal logo they could put on their web page?


    Funny, that'd *exactly* mirror the opinion I have of PHP :D

    (btw, why is this posted to every newsgroup EXCEPT a PHP one? make us
    feel good?)

    --
    Majority, n.: That quality that distinguishes a crime from a law.
     
    Ulrich Hobelmann, Dec 6, 2005
    #5
  6. Ulrich Hobelmann <> writes:

    > btw, why is this posted to every newsgroup EXCEPT a PHP one?


    Xah's a pretty well-known troll in these parts. I suppose he thinks someone
    is going to take the bait and rush to "defend" the other languages or some
    such nonsense.

    sherm--

    --
    Cocoa programming in Perl: http://camelbones.sourceforge.net
    Hire me! My resume: http://www.dot-app.org
     
    Sherm Pendley, Dec 6, 2005
    #6
  7. Xah Lee

    Jon Perez Guest

    Sherm Pendley wrote:

    > Xah's a pretty well-known troll in these parts. I suppose he thinks someone
    > is going to take the bait and rush to "defend" the other languages or some
    > such nonsense.


    Actually, I think Xah often has a point, except he can't
    seem to express it without resorting to profanity and
    a controlled manner, thus giving the impression he's a
    troll.

    Also, he seems to be blissfully unaware of the concept
    of netiquette. ;-)
     
    Jon Perez, Dec 7, 2005
    #7
  8. Jon Perez wrote:

    > Actually, I think Xah often has a point, except he can't
    > seem to express it without resorting to profanity and
    > a controlled manner, thus giving the impression he's a
    > troll.
    >
    > Also, he seems to be blissfully unaware of the concept
    > of netiquette. ;-)


    His "points" have about the same legitimacy as banging on the keyboard
    until it breaks and then crying for an hour. At least if he did that,
    we'd have to hear from him less.

    --
    Erik Max Francis && && http://www.alcyone.com/max/
    San Jose, CA, USA && 37 20 N 121 53 W && AIM erikmaxfrancis
    I want to know God's thought; the rest are details.
    -- Albert Einstein
     
    Erik Max Francis, Dec 7, 2005
    #8
  9. Xah Lee

    Gerald Klix Guest

    That's the most accurate description of Xah's behaviour I've read so far.

    Jon Perez schrieb:
    > Sherm Pendley wrote:
    >
    >
    >>Xah's a pretty well-known troll in these parts. I suppose he thinks someone
    >>is going to take the bait and rush to "defend" the other languages or some
    >>such nonsense.

    >
    >
    > Actually, I think Xah often has a point, except he can't
    > seem to express it without resorting to profanity and
    > a controlled manner, thus giving the impression he's a
    > troll.
    >
    > Also, he seems to be blissfully unaware of the concept
    > of netiquette. ;-)
    >
     
    Gerald Klix, Dec 7, 2005
    #9
  10. Xah Lee

    Xah Lee Guest

    Post-modernism, Academia, and the Tech Geeking fuckheads

    Post-modernism, Academia, and the Tech Geeking fuckheads

    • the Sokal Affair
    http://en.wikipedia.org/wiki/Sokal_Affair

    • SCIGen and World Multi-Conference on Systemics, Cybernetics and
    Informatics  
    http://pdos.csail.mit.edu/scigen/

    • What are OOP's Jargons and Complexities, Xah Lee
    http://xahlee.org/Periodic_dosage_dir/t2/oop.html

    • Politics and the English Language, George Orwell
    http://xahlee.org/p/george_orwell_english.html

    Xah

    ∑ http://xahlee.org/
     
    Xah Lee, Dec 8, 2005
    #10
  11. Xah Lee

    bradb Guest

    Re: Post-modernism, Academia, and the Tech Geeking fuckheads

    I don't know about anyone else, but you'd impress me much more if you
    didn't swear in your posts. I am personally not offended, but it does
    lower your credibility in my eyes. Just a tip.

    Brad
     
    bradb, Dec 8, 2005
    #11
  12. Xah Lee

    Xah Lee Guest

    PHP = Perl Improved

    recently i got a project that involves the use of php. In 2 days, i
    read almost the entirety of the php doc. Finding it a breeze because it
    is roughly based on Perl, of which i have mastery.

    i felt a sensation of neatness, as if php = Perl Improved, for a
    dedicated job of server-side scripting. Everything is so-built-in, and
    the integrated functions for web application programing such as
    CGI/Database is so convenient. What a PRACTICALITY! It has gotten a
    long way, even now with a independent interpreter and engine (Zend) for
    embedded computation of any other mark-up lang. And, its array/hash is
    kinda linguistically cleaner, by combining the two into one. (after
    all, array indexes are unique, so they are denotationally and
    mathematically list of keyed pairs (hashes) too) As for nested
    structure, it does away with Perl's ${x}->{'whatnot'}[$x]->[$y{'z'}]
    insanity. And I'm most impressed by its extremely well-written
    documentation.

    But as i know the lang more, my feeling changed, yet “Perl
    Improved†is still apt, with a new interpretation.

    see
    http://tnx.nl/php

    If Unix, Apache, Perl, MySQL etc shit can impact the world with
    motherfucking evolutionary outrageous $free$ lies, why should we fault
    Pretty Home Page?

    Xah

    ∑ http://xahlee.org/
     
    Xah Lee, Dec 9, 2005
    #12
  13. Xah Lee

    Roedy Green Guest

    Re: PHP = Perl Improved

    On 9 Dec 2005 11:15:16 -0800, "Xah Lee" <> wrote, quoted
    or indirectly quoted someone who said :

    >recently i got a project that involves the use of php. In 2 days, i
    >read almost the entirety of the php doc. Finding it a breeze because it
    >is roughly based on Perl, of which i have mastery.


    that's very lovely, but off topic. Trolling for language flame wars
    belong is comp.lang.java.advocacy.
    --
    Canadian Mind Products, Roedy Green.
    http://mindprod.com Java custom programming, consulting and coaching.
     
    Roedy Green, Dec 9, 2005
    #13
  14. Re: PHP = Perl Improved

    Roedy Green said something like:
    > On 9 Dec 2005 11:15:16 -0800, "Xah Lee" <> wrote, quoted
    > or indirectly quoted someone who said :
    >
    >> recently i got a project that involves the use of php. In 2 days, i
    >> read almost the entirety of the php doc. Finding it a breeze because it
    >> is roughly based on Perl, of which i have mastery.

    >
    > that's very lovely, but off topic. Trolling for language flame wars
    > belong is comp.lang.java.advocacy.


    I had plonked him back in May for this kind of crap. I suggest you do the
    same.

    --
    If I can ever figure out how, I hope that someday I'll
    succeed in my lifetime goal of creating a signature
    that ends with the word "blarphoogy".
     
    Thomas G. Marshall, Dec 10, 2005
    #14
  15. Xah Lee

    IchBin Guest

    Re: PHP = Perl Improved

    Thomas G. Marshall wrote:
    > Roedy Green said something like:
    >> On 9 Dec 2005 11:15:16 -0800, "Xah Lee" <> wrote, quoted
    >> or indirectly quoted someone who said :
    >>
    >>> recently i got a project that involves the use of php. In 2 days, i
    >>> read almost the entirety of the php doc. Finding it a breeze because it
    >>> is roughly based on Perl, of which i have mastery.

    >> that's very lovely, but off topic. Trolling for language flame wars
    >> belong is comp.lang.java.advocacy.

    >
    > I had plonked him back in May for this kind of crap. I suggest you do the
    > same.
    >


    It's better just to ignore him because he is only looking for the
    attention and pseudo respect..

    "You don't put a fire out with gasoline".

    --


    Thanks in Advance...
    IchBin, Pocono Lake, Pa, USA
    http://weconsultants.servebeer.com/JHackerAppManager
    __________________________________________________________________________

    'If there is one, Knowledge is the "Fountain of Youth"'
    -William E. Taylor, Regular Guy (1952-)
     
    IchBin, Dec 10, 2005
    #15
  16. Re: PHP = Perl Improved

    Roedy Green wrote:
    Of course I have Xah plonked but thanks to your

    > On 9 Dec 2005 11:15:16 -0800, "Xah Lee" <> wrote
    >> [...] Perl, of which i have mastery.


    I had the laugh of the week.
    Thank you very much, you really made my day.

    jue
     
    Jürgen Exner, Dec 10, 2005
    #16
  17. Xah Lee

    Tim Roberts Guest

    Re: PHP = Perl Improved

    "Xah Lee" <> wrote:

    >recently i got a project that involves the use of php. In 2 days, i
    >read almost the entirety of the php doc. Finding it a breeze because it
    >is roughly based on Perl, of which i have mastery.
    >
    >i felt a sensation of neatness, as if php = Perl Improved, for a
    >dedicated job of server-side scripting.


    The design of the PHP language is not too bad, and the standard library is
    extensive. It is quite possible to write well-structured, class-based web
    programs with PHP.

    However, it seems that almost no one actually does so. Virtually all of
    the vast PHP code samples on the web are crap. Maybe the simplicity of the
    language encourages inexperienced programmers who write spaghetti code
    without a thought to the structure; I don't know the exact cause, but I
    have seen it more often than not.
    --
    - Tim Roberts,
    Providenza & Boekelheide, Inc.
     
    Tim Roberts, Dec 10, 2005
    #17
  18. Xah Lee

    Dave Hansen Guest

    Re: PHP = Perl Improved

    On Sat, 10 Dec 2005 08:25:08 GMT in comp.lang.python, Tim Roberts
    <> wrote:

    [...]
    >
    >The design of the PHP language is not too bad, and the standard library is
    >extensive. It is quite possible to write well-structured, class-based web
    >programs with PHP.
    >
    >However, it seems that almost no one actually does so. Virtually all of
    >the vast PHP code samples on the web are crap. Maybe the simplicity of the
    >language encourages inexperienced programmers who write spaghetti code
    >without a thought to the structure; I don't know the exact cause, but I
    >have seen it more often than not.


    This reminds me of a comment that John Levine (moderator of
    comp.compilers) wrote in a post back in 1997: "It is my impression
    that it's possible to write good programs in C++, but nobody does."

    However, in the case of C++, I wouldn't blame "... the simplicity of
    the language ..."

    Regards,
    -=Dave

    --
    Change is inevitable, progress is not.
     
    Dave Hansen, Dec 12, 2005
    #18
  19. Xah Lee

    gene tani Guest

    Re: PHP = Perl Improved

    Tim Roberts wrote:
    > "Xah Lee" <> wrote:
    >
    > >recently i got a project that involves the use of php. In 2 days, i
    > >read almost the entirety of the php doc. Finding it a breeze because it
    > >is roughly based on Perl, of which i have mastery.
    > >
    > >i felt a sensation of neatness, as if php = Perl Improved, for a
    > >dedicated job of server-side scripting.

    >
    > The design of the PHP language is not too bad, and the standard library is
    > extensive. It is quite possible to write well-structured, class-based web
    > programs with PHP.
    >
    > However, it seems that almost no one actually does so. Virtually all of
    > the vast PHP code samples on the web are crap. Maybe the simplicity of the
    > language encourages inexperienced programmers who write spaghetti code
    > without a thought to the structure; I don't know the exact cause, but I
    > have seen it more often than not.
    > --
    > - Tim Roberts,
    > Providenza & Boekelheide, Inc.


    agreed, once you explain MVC, it's pretty hard to argue against it.

    Keeping from getting defaced is another matter. About a year ago, this
    page (or somethign very similar) was php.net's *homepage*, I almost
    fell over when i saw it. Moral of hte story, don't use shared server.

    http://www.php.net/security-note.php
     
    gene tani, Dec 12, 2005
    #19
  20. Re: Post-modernism, Academia, and the Tech Geeking fuckheads

    Xah Lee wrote:
    > Post-modernism, Academia, and the Tech Geeking fuckheads
    >
    > • the Sokal Affair
    > http://en.wikipedia.org/wiki/Sokal_Affair
    >
    > • SCIGen and World Multi-Conference on Systemics, Cybernetics and
    > Informatics
    > http://pdos.csail.mit.edu/scigen/
    >
    > • What are OOP's Jargons and Complexities, Xah Lee
    > http://xahlee.org/Periodic_dosage_dir/t2/oop.html
    >
    > • Politics and the English Language, George Orwell
    > http://xahlee.org/p/george_orwell_english.html
    >
    > Xah
    >
    > ∑ http://xahlee.org/
    >


    I agree with everything you say. You should check
    out the following links. They will amuse and
    enlight you.

    Post-modernism, Schizo-Islamism and the world at large:
    http://www.rhfweb.com/mctom.html

    S.N.A.F.U., D.I.S.C.O. and C.R.I.S.I.S. reaching crisis
    proportions:
    http://koti.welho.com/mjack1/

    The Dalai Llama is just another EVIL spitting mammal:
    http://pages.123-reg.co.uk/sumon-262452/

    It's a pussy-eat-pussy world. Tech Geek fuckheads might beg
    to disagree, however:
    http://www.johnnydisco.com/

    Secularism, homosexuality, fringe humor finally dominating
    occidental tech elite. End neigh, doctors say:
    http://www.qgeeks.org

    Don't mention it, at your service
    Tin
     
    Tin Gherdanarra, Dec 14, 2005
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Xah Lee
    Replies:
    9
    Views:
    371
    John Bokma
    Jul 19, 2005
  2. Xah Lee
    Replies:
    0
    Views:
    370
    Xah Lee
    Nov 24, 2005
  3. Xah Lee
    Replies:
    80
    Views:
    1,683
    Claudio Grondi
    Feb 16, 2006
  4. Xah Lee
    Replies:
    22
    Views:
    1,184
    Tim Roberts
    Mar 21, 2006
  5. Xah Lee
    Replies:
    79
    Views:
    690
    Alan Mackenzie
    Mar 9, 2006
Loading...

Share This Page