develooper Front page | perl.perl5.porters | Postings from June 2012

proposed/drafted new perl docs

From:
Uri Guttman
Date:
June 7, 2012 21:35
Subject:
proposed/drafted new perl docs
Message ID:
4FD18010.4000500@stemsystems.com

hi all,

some time last year, leopold asked about ways to improve a perl site.
this got me going on new perl docs i felt were needed. i have drafts of
3 and an outline for a fourth. you can see them at:

http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=urisagit/Perl-Docs.git;a=tree

metadoc is about how to use the doc tools and techniques to help you
read the perldocs. we have so many docs and ways to read them there
needs to be a central place to help out newbies with this. it is mostly
done but patches/edits welcome.

perlblurb is just an expansion of perldoc perl with a paragraphs about
each doc and cross references to other related docs.  much of it is
written but this is sure to be wrangled over a bit. feel free to add in
the missing parts and edit existing ones. the goal here is to make a
browsable doc where you can learn quickly which are the relevent docs
for your needs. a one liner in perldoc perl just isn't enough,
especially with so many docs.

perladvantages is meant to be a non-flaming set of reasons to use perl.
we do have many technical and cultural advantages. i only cover 4 of
them and i am sure we know of other wins we can document. so many times
we are asked why perl vs **** and we need a place to point to with
all the best answers.

perlresources overlaps with perlcommunity but it could have a different
take. the name is better IMO as not every resource is a community thing.
it is just an outline so far and it needs much work. if we come up with
a way to make this different than the other doc but useful in its own
right, it would be a win. if it dies on the vine, i will survive that. i
just checked the 5.16 version and it still mentions use.perl.org but not
blogs.perl.org. there are many more useful resources out there so this
doc could have a life of its own.

i sent this to ricardo and he skimmed them and said to post it here. sue
him, not me! i will be at yapc and would like to brainstorm/hack/edit
these with anyone who wants to help. mst could get you a commit bit
maybe to make it easier (he is hosting the git, thanx!).

all the docs are plain text and need podding too. any pod gurus, please
jump in!

thanx,

uri








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