develooper Front page | perl.perl5.porters | Postings from March 2011

"Web-enabled" documentation

Thread Previous | Thread Next
From:
Jesse Vincent
Date:
March 4, 2011 10:59
Subject:
"Web-enabled" documentation
Message ID:
20110304185934.GB2297@fsck.bestpractical.com
There is no compelling reason why we have to write our docs in such a
way that they're unusable from the commandline or in a browser.

There's nothing wrong with providing links to additional resources on the
web that will help perl programmers write better programs, as long as our
core docs don't defer coverage of essential topics to external websites.

Programmers need to be able to use Perl's docs on an airplane or in a
secure environment that has no Internet access, but there's no reason
to go all Harrison Bergeron on programmers who aren't cut off from the
Internet.

Similarly, if our docs can be reasonably cross-linked such that
programmers viewing them in a documentation reader capable of following
links have links to follow, that's great.  If the only way to read
Perl's docs is to have a WebGL enabled copy of Firefox with an embedded
PDF viewer and a copy of TeX ported to Javascript, that's not so great.

Some of us do not read pod in a browser. Some of us do not
read pod with perldoc. Some of us do not read pod with man.  Myself,
I only read pod with green eggs and ham.  Anything we can do to help
people read docs is a good thing.


Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About