I am excited to announce the formation of the Perl 5 Documentation Team. Our goal is to have the best, most current, and easiest to use and understand documentation of any programming language. Why settle for small goals?
Since the success of this team will depend on having both expert and novice points of view, membership is open to all, regardless of experience level with Perl. This is an excellent opportunity for people who would like to make a contribution back to the Perl community to do so in a way that doesn't require expert programming abilities.
If you are interested in being part of the team, please subscribe to the Perl Documentation mailing list, as future discussion will occur there (look for the thread named "I want to sign up"). If you know of other people who may be interested in being part of this effort, please pass this message on to them.
Areas where the team will be active include:
- Reviewing and updating documentation to ensure that it is friendly to new users
- Updating examples in documentation to a style compatible with Modern Perl practices
- Updating the documentation so that all examples longer than one line contain a
usestatement indicating the minimum version of Perl 5 required to run the example - Monitoring p5p for incoming documentation patches, ensuring they contain a patch against the current delta, and forwarding them to committers as needed
- Monitoring p5p for patches that will require modification of documentation, and ensuring that the documentation is modified appropriately
- Verifying that perlglossary contains current accurate definitions for all jargon terms
Goals to be met for the Perl 5.14.0 release include:
- Recruit novice and experienced Perl programmers to the team, and create a Perl module (a la Perl::Staff) and a Perl 5 wiki entry listing the team members
- Finalize perlopquick as a replacement for perlop and modify the new perlop so that perlop and a shorter perlopref can be generated from a single source document
- Extend perldoc to use the new perlop to provide documentation on operators (tenative proposal: perldoc -O "^=")
- Create a perlfuncref, a series of short summaries of information in perlfunc, analogous to perlopref (Again, both of these will be generated from a single source document for ease of maintenance)
- Define a policy for documenting documentation changes in the Perl deltas (e.g. perl5133delta.pod)
- Define a set of documentation style guidelines, covering structure, style, and content
- Formally define the Perl 5 Documentation Team functions
- Set deadlines for the defining of longer term goals
- Create a logo for the Perl 5 Documentation Team
- Find a better name or nickname for the Perl 5 Documentation Team
Potential longer term (post-5.14.0) goals:
- Clean up perlre
- Extensive review and Modernization of all examples
- Develop a plan to integrate with the Pod2 translation project
So this blog post documents the documentation of documenting documentation changes? I don't get it.
ReplyDeleteSeriously though this is very exciting, especially the perldoc -O stuff.
@fREW No, this blog post documents the desire to document manner in which we will document the documentation changes.
ReplyDeleteI see lots of stuff about fiddling aroung edges, adding use 5.10.0 for example.
ReplyDeleteIf you want the best documentation of any language, where's the stuff about screencast tutoruals and YouTube channels and stuff that would bring us closer to people like Ruby.
@Adam This is a good point that I had not even considered. I was thinking of only improving the core documentation, but you are right, there is more to documentation than the core docs. I will have to think about what to cover; I guess this means researching what Ruby has done.
ReplyDeleteYour pet committer stands ready.
ReplyDeleteThis is going to be fucking epic.
-- mst