root/docs/README

===============================================================================
= Pugs Docs Directory
===============================================================================

- What is this directory?

This directory is meant to contain documentation, links to related papers
and sites, design notes, etc.

- How can I contribute?

Pick a topic, document it, ask for a commiter bit, and upload it.  If there
are relevant papers or talks that we don't already have, please convert the
documents to one of our preferred documentation formats (see below) and
commit, or link to them from READTHEM or docs/talks/README.

- What should I document?

Whatever you like. There are no restrictions or expectations, and the more
the merrier.

- What document format is preferred?

Plain text/minimal markup document formats are preferred, such as POD,
Kwid, Spork, and so on.  There seems to be a preference for Kwid for most
general documents, POD for AES drafts, Spork for slides, and completely
raw text for quickrefs.

- What directory is appropriate for a new document?

The documentation tree is in a state of flux at the moment, but a few rules
seem to have rough consensus:

** Documentation for Perl 6 modules belongs with the relevant module.

** Perl 5 modules providing Perl 6 functionality or Pugs interoperability
   belong in lib/, together with their documentation.

** Don't create personalized directories, such as docs/billgates_thoughts.
   This fragments the tree too much, makes others uneasy about fixing
   documents in that directory, and sorts by author instead of category.

** Sort by category within docs/, if possible.  Create a new category if
   none of the existing ones apply, but see below.

** A few document types have standard docs/ locations already:
*** docs/quickref for quick reference pages
*** docs/talks    for talks/slides
*** docs/AES      for AES drafts

** docs/notes/ is for general Perl 6 or Pugs design notes, but please
   don't use this as a catch-all.  It's much better to create a useful
   category and begin to fill it in.  Documents created here anyway are
   likely to be moved once appropriate categories do exist.

If none of these apply, and you're still not sure where your document
belongs, ask on #perl6, or put it in docs/other/ and email perl6-compiler
to let us know.