--- OldDocHelp 2008-03-10 20:52:47.000000000 -0700 +++ NewDocHelp 2008-03-10 22:11:26.000000000 -0700 @@ -16,32 +16,63 @@ .. |contribute_docs| image:: 1.0/RoughDocs/contribute_docs.jpg +Three Ways to Help +------------------ + There are three ways to help make and maintain TurboGears documentation: #. Comment! Pages should all have a comments box at the bottom. Add your comments if you see a problem. -#. Add to the RoughDocs section for the version of TurboGears you're using. - Anyone can add and edit documentation there. Please do! +.. Note:: Note: Comment sections have been increasingly locked up due to wiki + spamming. Sorry for this inconvenience. + +2. `Add to the RoughDocs`_ section for the version of TurboGears you're using. + Anyone can add and edit documentation there following the directions below. + Please do! #. Become an editor! Knowledgeable TurboGears users with the interest and - aptitude can become editors. Editors are able to edit the "official" docs. + aptitude can become editors. Editors are able to edit the "official" docs. + To get involved, visit the `documentation team page + `_. + + +.. _Add to the RoughDocs: + +How to Add or Change Documentation +---------------------------------- + + +Putting Docs in the Right Places +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All docs about the TurboGears framework *must* have a version number at the +beginning of the page name (i.e the last part of the URL), in sub wiki syntax. +If you write a page about Apache deployment for TurboGears 1.0, that page +should be called "``1.0/ApacheDeployment``". + +New articles should be linked from the RoughDocs page for the applicable +version (e.g. `1.0/RoughDocs <1.0/RoughDocs>`_) until they have been reviewed +and approved by the editors and given "official" status. This also ensures that +new documents don't get lost and others can benefit from and/or contribute to +them immediately. + +Multi-page documents should use the sub wiki format to reflect the pages, e.g. +"``1.0/20MinuteWiki/Page1``". + -If you're looking to contribute docs in RoughDocs or as an editor, be sure -to read the following sections and the `documentation team page `_. +Documentation Format & Style Guidelines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In an effort to keep the documentation consistent online and useful offline, +please follow these conventions: -Documentation Format --------------------- -All documentation should be in ReStructuredText format, not the standard wiki -markup. This is very important for ensuring the long term value of the docs we -write. We expect to move to another documentation system at some point in the -future, or we might want to convert the docs to printable form. The use of -ReStructuredText will allow us to do that without complex document conversions. +All documentation should be in *ReStructuredText (ReST)* format, **not the standard wiki +markup** [#]_. There are two templates that should be used to get you going with your document. -Both templates set the format to ReST and they also include the proper code to +Both templates set the format to `ReST Formatting`_ and they also include the proper code to include the page comment form. OfficialTemplate @@ -51,8 +82,8 @@ For any contributed or unofficial docs. -ReST Syntax -~~~~~~~~~~~ +Designating ReST Syntax +``````````````````````` Please note that if you choose not to use one of these templates you will have to explicitly tell MoinMoin that you are using ReST syntax. This is done by @@ -60,17 +91,11 @@ #format rst -MoinMoin includes a page with a `ReStructuredText primer`_ and also includes -information on the `use of ReST in MoinMoin`_. - -Please also note the addtional notes on proper ReST formatting below. - -.. _restructuredtext primer: HelpOnParsers/ReStructuredText/RstPrimer -.. _use of rest in moinmoin: HelpOnParsers/ReStructuredText +Proper `ReST formatting`_ syntax is discussed below. Page Status -~~~~~~~~~~~ +``````````` All documentation pages should display their editorial status right below the main heading (like this page does). Use the `field lists syntax`_ for the @@ -89,7 +114,7 @@ Table of Contents -~~~~~~~~~~~~~~~~~ +````````````````` All pages with longer than a screen page should have a table of contents. This will be generated automatically by the wiki software from the section @@ -102,84 +127,70 @@ be included in the table of contents. -Putting Docs in the Right Places --------------------------------- - -All docs about the TurboGears framework *must* have a version number at the -beginning of the page name (i.e the last part of the URL), in sub wiki syntax. -If you write a page about Apache deployment for TurboGears 1.0, that page -should be called "``1.0/ApacheDeployment``". - -New articles should be linked from the `RoughDocs <1.0/RoughDocs>`_ page for the -proper version as long as they haven't been checked and approved by the editors -and given an "official" status. This also ensures that new documents don't get -lost and others can benefit from them and/or contribute. - -Multi-page documents should use the sub wiki format to reflect the pages, e.g. -"``1.0/20MinuteWiki/Page1``". - - -Style Guidelines ----------------- - -In an effort to keep the documentation consistent online and useful offline, -please follow these conventions: - Language & Style -~~~~~~~~~~~~~~~~ +```````````````` #. **Please pay attention to proper spelling, grammar, and style!** - For example, all full sentences should end with a full stop, proper names - should be capitalized, common word contractions should be written out - (i.e. "you should" instead of "you'd") and so on. - -#. Avoid too many abbreviations and jargon speak. Not every reader of the - docs is an English native speaker! + For example, + * All full sentences should end with a full stop. + * Proper names should be capitalized. + * Common word contractions should be written out + (i.e. "you should" instead of "you'd", etc.) + +2. Avoid too many abbreviations and jargon speak. + +#. Avoid slang and idioms (e.g. "This should be a piece of cake.") Not every + reader of the docs is a native English speaker so it will not always + mean what you meant it to mean! #. All major words in the page title and headings should be capitalized - ("This is a Good Heading"). The exceptions are articles, conjunctions, - and short prepositions, etc.) + (e.g. "This is a Good Heading", but "This is not a good heading".) The + exceptions are articles, conjunctions, and short prepositions, etc. #. Use literal syntax (see below) for names of Python objects, functions, modules etc., shell commands, software packages, and so on. - #. A full command line should go in a block literal (see below) so that it is easier to notice. -#. The name for an example project (e.g. ``Wiki 20`') is ```` +#. The name for an example project (e.g. ``Wiki 20``) is ```` and the Python package name (e.g. ``wiki_20``) is ````. ReST Formatting -~~~~~~~~~~~~~~~ +``````````````` -#. Please keep the ReST source nicely formatted by wrapping lines at 80 - characters, inserting two empty lines before and one after each heading - and keeping the indentation of literal blocks consistent. +Some markup guidelines and essentials of ReST syntax are listed below. For +summary reference, visit this `Quick Reference page`_ or this more +`extensive list`_. - In short, treat the ReST source as you would treat Python source code. - You want this to be beautiful as well, don't you? +Treat the ReST source as you would treat Python source code by making it +nicely formatted and beautiful. When it helps, you can edit the page source +in your local editor and paste it back into the wiki editor interface when +you ready. - You can edit the page in your local editor and paste it back to the - wiki editor interface when you ready. +#. Wrap ReST source lines at 80 characters. + +#. Insert two empty lines before and one after each heading. + +#. Keep the indentation of literal blocks consistent. #. The page title should be underlined with equal signs (``=``). #. Section headings should be underlined with ``-`` (dash), ``~`` (tilde), and ` (backtick), according to their level in the section hierarchy in the order given here. Keep the underline the same length as the section - title (you can do this in the final proof-reading phase). + title. -#. Literals are any chunk of code (including variable names and parameters) +#. Literals are any chunk of code, including variable names and parameters and anything you type directly into a terminal. Literals are surrounded - by double backticks. If you run across one of the few instances of the + by double backticks. (If you run across one of the few instances of the older convention of surrounding literals with quotes, please drop the - quotes and replace with double backticks. + quotes and replace with double backticks.) #. Block literal sections are for longer examples and command lines. @@ -209,27 +220,29 @@ .. _example link: 1.0/ExampleLink - If the URL is very long, you can put a line break behind the colon and indent - the URL on the next line. Put the all URLs from one section at the end of + * If the URL is very long, you can put a line break after the colon and indent + the URL on the next line. + + * Put the all URLs from one section at the end of the section. - One-word links don't need backticks: ``mylink_``. + * One-word links don't need backticks: ``mylink_``. - The link target should not be enclosed in backticks and case does not matter. + * The link target should not be enclosed in backticks and is not case-sensitive. -#. Try to use list syntax for lists instead of formatting the lists yourself by - using bold text or italicized text. This mostly comes up when dealing with - lists of arguments etc., check the `Configuration <1.0/Configuration>`_ page - for an example:: +9. Try to use list syntax for lists instead of formatting the lists yourself + with bold or italics. This mostly comes up when dealing with lists of + arguments etc. The `Configuration <1.0/Configuration>`_ page is a good + example:: ``arg1`` argument 1 explanation text ``arg2`` argument 2 explanation text -#. First-level list have *no* indentation in the ReST source. +#. First-level lists have *no* indentation in the ReST source. -#. For ordered lists, don't number the items yourself, use this syntax instead:: +#. For ordered lists, don't number the items yourself. Use this syntax instead:: #. Item one #. Item two @@ -238,6 +251,7 @@ #. You can also break lines in lists, footnotes and notes, if you indent the second and following lines the same level. + For list items, the indentation level must match that of the first letter on the first line, e.g.:: @@ -247,37 +261,113 @@ Like this. + +Remember, pages marked with "Official[, Approved]" are considered to be +accurate, reviewed and have proper style. Copy editing is an essential +part of maintaining high quality documents. + .. _callout style: - http://docutils.sourceforge.net/docs/user/rst/quickref.html#contents + http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets -Editor Guidelines ------------------ -If you bless a page by marking it as official, please send a note to -turbogears-docs saying so. We, the DocTeam_, would like to keep track -of things without missing them in the noise of RecentChanges_ and I'm -sure you would as well. +Document Submission Procedure +----------------------------- -If you work on a document that is marked official, please +Newly Created Documents +~~~~~~~~~~~~~~~~~~~~~~~ -#. Take extra care. +While working on a new document, set the status to *"Work in progress"*. -#. Set the status to "Official, Work in progress" while you are working - on it and to "Official, Draft" until at least one other person had a - chance to look at your changes. +Once completed to your satisfaction, + +#. Change status to *"Draft"*. + +#. Open a new Trac ticket requesting a review. (See `Opening New Document Tickets`_ + below.) + + + +Improvements upon Existing Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Editable Documents +`````````````````` +* If you think you know what you are doing: + + #. Edit document directly. + #. Do not open a ticket. + +* If you have doubts: + + #. Edit what you can. + #. Open *one* ticket for review and all the rest of the issues with that page + +Official Documents +`````````````````` + +If you work on a document that is marked *Official*, + +* If you have write access: + + #. Please take extra care. + + #. Set the status to "Official, Draft" until at least one other person has + had a chance to look at your changes. + + #. Open a new ticket. + +* If you do not have write access: + + #. Download raw text of the original document. + #. Make changes at your local computer. + #. Create a diff file of your changes with `diff -u old new`. + #. Open a new ticket. + #. Attach diff file to ticket. + + +Opening New Document Tickets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. Open a `new Trac ticket`_. + +#. Put the document's title in the ticket summary + +#. Set Component=Docs + +#. Set Version=X.0 (one decimal place only) + +#. Set Keywords to "doc review" + +#. If you could not edit the document yourself, attach a diff file + of your proposed changes. + +.. _new Trac ticket: http://trac.turbogears.org/newticket -Remember, pages marked with "Official[, Approved]" are considered to be -accurate, reviewed and have proper style. Copy editing is an essential -part of maintaining high quality documents. Resources --------- -* There are some wiki ReST syntax snippets ready to be copied and pasted - on Chris Arndt's `personal wiki page`_ -* There is a list with further resources for documentation writers on the - `documentation team page`_. +.. * There are some wiki ReST syntax snippets ready to be copied and pasted + on Chris Arndt's `personal wiki page`_ + +* `Documentation Team Page`_ +* `ReST Quick Reference`_ +* Lots of `ReST Information`_ +* `RoughDocs Page for 1.0 <1.0/RoughDocs>`_ +* `TurboGears Trac `_ .. _personal wiki page: ChristopherArndt/Snippets + +.. [#] This is very important for ensuring the long term value of the + docs we write. We expect to move to another documentation system + at some point in the future, or we might want to convert the docs to + printable form. The use of ReStructuredText will allow us to do + that without complex document conversions. + +.. _ReST Information: +.. _extensive list: http://docutils.sourceforge.net/rst.html +.. _quick reference page: +.. _ReST Quick Reference: + http://docutils.sourceforge.net/docs/user/rst/quickref.html +