Xah's Edu Corner: Examples of Quality Technical Writing

Discussion in 'Perl Misc' 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" <> 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
    #2
    1. Advertising

  3. 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
    #3
  4. 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
    #4
  5. 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
    #5
  6. 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
    #6
  7. 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
    #7
  8. 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
    #8
  9. 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
    #9
  10. Xah Lee

    robic0 Guest

    Re: PHP = Perl Improved

    On Sat, 10 Dec 2005 08:25:08 GMT, 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.


    I assume you are young or new relatively in years to programming.
    I have unfortunately chosen to stay with it over the years, over
    25 years now. This guy Xah is a fuckin idiot as with most asians
    (just my opinion). There is no company out there that won't exploit
    you for "flash" programming quick fixes. Mostly to fix the "last"
    programmer in the chain's code. Be aware that if you continue
    you will be looking forward to a fucked professional life.
    The way I've avoided extinsion, for the most part, is to give
    the corporate world what they want and alot more of extremely
    sophistocated code that they can't hire or move the lifers
    to readily decode. Unfortunately, thats the way of life as
    it exists now in the proffesional market. I will hack your
    balls off, basically destroy your chances of you getting
    my job at a lower price and me getting canned. If you don't
    think thats the way it is your head needs to be examined.
    So when you get a professional job, you "won't" be writing
    original code, you will be spending most of your time analyzing
    some other shmuchkss code to modify it. If the shmuck was any
    good, you wouldn't have been hired in the first place. I've been
    a contractor for the the last 10 years, and I've never been layed off.
    If I wanted to stay for 2,3 or 5 years I did. When I wanted to leave
    I did. I controlled because of the code I wrote. Unfortunately for
    you, there are alot out there like me. I've made up to 120/hr.
    I've worked on the hardest most complex code out there. I've
    put myself in a creative, code origination position. When I've
    had to take on others code, I mostly gutted it and put my own in.
    Make no mistake, the code is top quality, mostly original and
    creative. The creative part makes me stay with it.

    If I were you, I would NOT take up Perl. Nor would I take up
    programming as a proffession if I had it to do over again.

    robic0
     
    robic0, Dec 10, 2005
    #10
  11. 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
    #11
  12. 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
    #12
  13. 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 suspect that you are a computer program posing as a human
    usenet correspondent.

    Please answer these questions:

    If Alice goes to the supermarket to buy a pint of
    milk, does her head go with her? Please elaborate.

    What is the difference between my disher blowing
    a fuse and your boss blowing a fuse? Please elaborate.

    How can you turn off the light of a candle? Why does
    it work?
     
    Tin Gherdanarra, Dec 14, 2005
    #13
  14. Re: PHP = Perl Improved

    -----BEGIN PGP SIGNED MESSAGE-----
    Hash: SHA1

    >>>>> "Tin" == Tin Gherdanarra <> writes:


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


    Tin> I suspect that you are a computer program posing as a human
    Tin> usenet correspondent.

    Tin> Please answer these questions: [...]

    Will you accept a solution in Perl? He has mastery of that language,
    you know. You might have better luck if you phrase your questions in
    Perl, too, since he doesn't seem to understand it when people tell him
    to bugger off in plain English.

    Say, there's a thought...

    Martin
    -----BEGIN PGP SIGNATURE-----
    Version: GnuPG v1.4.1 (GNU/Linux)
    Comment: Using Mailcrypt+GnuPG <http://www.gnupg.org>

    iEYEARECAAYFAkOg0CUACgkQYu1fMmOQldVP9ACfSzQBq7S1QX0jA2/nA2JaC+BB
    4ZoAoMOn5Qe9oJHGtINWKNBQsz879R6r
    =bp6G
    -----END PGP SIGNATURE-----
     
    Martin Christensen, Dec 15, 2005
    #14
  15. Xah Lee

    javuchi Guest

    Why do you have such a need of being hating everything and everybody
    and expressing it so offen?
    Can you live without hate?
    Can you let others live without your hates?
     
    javuchi, Dec 15, 2005
    #15
  16. Xah Lee

    robic0 Guest

    On Wed, 14 Dec 2005 20:31:54 -0700, "Luc The Perverse"
    <> wrote:

    >"javuchi" <> wrote in message
    >news:...
    >> Why do you have such a need of being hating everything and everybody
    >> and expressing it so offen?
    >> Can you live without hate?
    >> Can you let others live without your hates?

    >
    >A person can live without hate, living love and working towards bettering
    >humanity.
    >
    >But as for people in general - I'm not so sure. I'm not sure my opinion on
    >hate - since I value people's opinions and diversity, hate seems unbecoming,
    >but then so does computer gaming ;)
    >
    >Westernization sweeps accross all countries though, and it is no longer
    >vogue to be so self centered. This will help with the most overt types of
    >hatred.


    robic0 ....... AMERICAN, and fuckin proud of it !!!!!!!!!!!!
     
    robic0, Dec 15, 2005
    #16
  17. Xah Lee

    John Bokma Guest

    Re: PHP = Perl Improved

    Martin Christensen <> wrote:

    > Perl, too, since he doesn't seem to understand it when people tell him
    > to bugger off in plain English.


    "It" buggers off if everybody ignores it. "It" posts because it knows that
    its actions pisses off so many people.

    --
    John Small Perl scripts: http://johnbokma.com/perl/
    Perl programmer available: http://castleamber.com/
    I ploink googlegroups.com :)
     
    John Bokma, Dec 15, 2005
    #17
  18. Xah Lee

    robic0 Guest

    Re: PHP = Perl Improved

    On Wed, 14 Dec 2005 20:37:53 +0100, Tin Gherdanarra
    <> 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 suspect that you are a computer program posing as a human
    >usenet correspondent.
    >
    >Please answer these questions:
    >
    > If Alice goes to the supermarket to buy a pint of
    > milk, does her head go with her? Please elaborate.

    Yes, but its in the shopping cart she's pushing
    >
    > What is the difference between my disher blowing
    > a fuse and your boss blowing a fuse? Please elaborate.

    Lips
    >
    > How can you turn off the light of a candle? Why does
    > it work?

    Leave and go into a dark room then poke your eyes out.
    I only heard it works.
     
    robic0, Dec 15, 2005
    #18
  19. Re: PHP = Perl Improved

    Martin Christensen <> writes:

    >>>>>> "Tin" == Tin Gherdanarra <> writes:

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

    >
    > Tin> I suspect that you are a computer program posing as a human
    > Tin> usenet correspondent.
    >
    > Tin> Please answer these questions: [...]
    >
    > Will you accept a solution in Perl? He has mastery of that language,
    > you know. You might have better luck if you phrase your questions in
    > Perl, too, since he doesn't seem to understand it when people tell him
    > to bugger off in plain English.


    OK, lets try:

    die;

    --
    Måns Rullgård
     
    Måns Rullgård, Dec 15, 2005
    #19
  20. Xah Lee

    Xah Lee Guest

    Re: Xah's Edu Corner: Responsible Software Licensing

    Responsible Software Licensing

    Xah Lee, 200307

    Software is a interesting invention. Software has this interesting
    property, that it can be duplicated without cost, as if like copying
    money. Never in history are goods duplicable without cost. But with the
    invention of computer, the ephemeral non-physical programs break that
    precept. In digital form, programs and music and books all become goods
    in essentially infinite quantity.

    All is good except, bads in digital form can also multiply equally,
    just as goods. Well known examples are computer viruses and email
    spams. Unknown to the throng of unix morons are software bads. In a
    unix moron's mind, the predominant quip among hackers is “where is
    your code?â€, singnifying the mentality that a hacker's prestige is
    judged on how much code he has contributed to the community. Therefore,
    every fucking studs and happy-go-lucky morons put their homework on the
    net, with a big stamp of FREE, and quite proud of their
    “contributions†to the world. These digital bads, including
    irresponsible programs, protocols, and languages, spread like viruses
    until they obtained the touting right of being the STANDARD or MOST
    POPULAR in industry, as if indicating superior quality. Examplary are
    C, Perl, RFC, X-Windows, Apache, MySQL, Pretty Home Page (and almost
    anything out of unix). The harm of a virus is temporal. The harm of
    irresponsible software (especially with unscrupulous promotion) is the
    creation of a entire generation of bad thinking and monkey coders. The
    scale can be compared as to putting a bullet in a person brain, versus
    creating a creed with the Holocaust aftermath.

    Distribution of software is easily like pollution. I thought of a law
    that would ban the distribution of software bads, or like charging for
    garbage collection in modern societies. The problem is the difficulty
    of deciding what is good and what is bad. Like in so many things, i
    think the ultimate help is for people to be aware; so-called education;
    I believe, if people are made aware of the situation i spoke of, then
    irresponsible software will decrease, regardless any individual's
    opinion.

    The most important measure to counter the tremendous harm that
    irresponsible software has done to the industry is to begin with
    responsible licenses, such that the producer of a software will be
    liable for damage incurred thru their software. As we know, today's
    software license comes with a disclaimer that essentially says the
    software is sold as is and the producer is not responsible for any
    damage, nor guaranteeing the functionality of the software. It is this,
    that ferments all sorts of sloppitudes and fads and myths to rampage
    and survive in the software industry. Once when software producers are
    liable for their products, just as bridge or airplane or transportation
    or house builders are responsible for the things they build, then
    injurious fads and creeds the likes of (Perl, Programing Patterns,
    eXtreme Programing, “Universal†Modeling Language...) will
    automatically disappear by dint of market force without anyone's
    stipulation.

    In our already established infrastructure of software and industry
    practices that is so already fucked up by existing shams, we can not
    immediately expect a about-face in software licenses from 0 liability
    to 100% liability. We should gradually make them responsible. And this,
    comes not from artificial force, but gradual establishment of awareness
    among software professionals and their consumers. (Producers include
    single individual to software houses, and consumers include not just
    mom & pop but from IT corps to military.)

    Please spread this idea.
    --------------------------------
    This post is archived at
    http://xahlee.org/UnixResource_dir/writ/responsible_license.html

    Xah

    ∑ http://xahlee.org/
     
    Xah Lee, Dec 17, 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:
    355
    John Bokma
    Jul 19, 2005
  2. Xah Lee
    Replies:
    0
    Views:
    353
    Xah Lee
    Nov 24, 2005
  3. Xah Lee
    Replies:
    80
    Views:
    1,654
    Claudio Grondi
    Feb 16, 2006
  4. Xah Lee
    Replies:
    22
    Views:
    1,143
    Tim Roberts
    Mar 21, 2006
  5. Xah Lee
    Replies:
    102
    Views:
    1,514
    dcrockett355
    Mar 12, 2006
Loading...

Share This Page