This is a list of the short term goals for the Perl 5 Documentation
Team, the tasks needed to make the goal a reality, and the deadlines
for those tasks.
Overall hard deadline: 1st quarter 2011
Administrative Tasks:
--------------------
* Define the activities of the Perl 5 Doc Team (deadline 2010-07-10)
Discuss in the "Proposed activities of the Perl 5 Doc Team" thread in [the
mailing list][1].
* Define a policy for documenting documentation changes in the Perl
deltas (e.g. perl5133delta) (deadline 2010-07-10)
Discuss in the "Proposed documenting of documentation changes" thread in the
mailing list.
* Create a FAQ (deadline 2010-07-10)
Suggest questions and answers to the "Proposed FAQ" thread in the
mailing list.
* Create a CPAN module and Perl 5 wiki entry listing members
(ongoing, Module and wiki entry will be created by 2010-12-10)
People who wish to be listed as members should reply to the "I want
to sign up" thread in the mailing list with the task(s) they wish to
undertake.
* Create a logo and/or mascot for the Doc Team (deadline 2010-07-31)
People with (or without) artistic talent are encouraged to submit
logo and mascot ideas to the "Proposed logo and/or mascot" thread in
the mailing list (WARNING: if we get no submissions then I will
choose some incredibly boring Creative Commons licensed image that I
think fits).
* Set tentative dates for some of the long term goals (deadline
2010-08-31)
More on this later.
Documentation tasks:
-------------------
* Define guidelines for writing official documentation (deadline
2010-08-31)
We need to
- Examine the structure of the existing documentation
- Identify the individual types of documentation (tutorial,
manual, quick reference, glossary, etc.)
- Suggest guidelines for writing new documentation in the
"Proposed documentation guidelines" thread in the mailing list.
* Create perlfuncref (deadline 2010-10-31)
We need to
- Determine the best way to generate `perlfunc` and `perlfuncref`
from a single source
- Add single line descriptions of the functions
* Replace `perlop` with `perlopquick` (deadline 2010-12-31)
We need to
- Add any missing operators (I think <> is missing)
- Review entries for correctness
- Review entries for clarity
- Correct any style issues based on guidelines created by the Doc
team
- Add use statements to every example to indicated the minimum
level of Perl to run the example
- Make it easy to do automated testing on examples
- Add sections linked from perlop to the document as appendices
and change the links to internal ones
- Use the same technique from `perlfunc`/`perlfuncref` to generate
`perlop` and `perlopref`
* Modify `perldoc` to display individual operators (deadline
2010-12-31)
We need to either add a new switch like `-O "||="` or possibly
rethink how function, variable, and operator lookups work (e.g.
maybe `-h` could take a string as an argument and we would determine
the right file to find the answer in)
[1]: http://lists.perl.org/list/perl-documentation.html
--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
