neysx 06/03/21 21:55:23 Modified: doc-tipsntricks.xml Log: #100026 Added submitters tips. Thanks to rane for initiating it and to nightmorph for turning it into English :)
Revision Changes Path 1.14 xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.14&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.14&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml.diff?r1=1.13&r2=1.14&cvsroot=gentoo Index: doc-tipsntricks.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- doc-tipsntricks.xml 21 Mar 2006 12:17:12 -0000 1.13 +++ doc-tipsntricks.xml 21 Mar 2006 21:55:23 -0000 1.14 @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v 1.13 2006/03/21 12:17:12 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v 1.14 2006/03/21 21:55:23 neysx Exp $ --> <guide link="/proj/en/gdp/doc/doc-tipsntricks.xml"> <title>Documentation Development Tips & Tricks</title> @@ -20,8 +20,8 @@ <license/> -<version>0.18</version> -<date>2005-03-21</date> +<version>0.19</version> +<date>2006-03-21</date> <chapter> <title>Setting up your local environment</title> @@ -417,6 +417,84 @@ </chapter> <chapter> +<title>Documentation Submission Tips</title> +<section> +<title>Check for correct <guide> tags</title> +<body> + +<p> +Make sure that the <guide link> attribute points to the correct location +for the guide. This is generally <path>/doc/${LANG}/filename.xml</path>. If you +have a translated document, always specify the absolute path to the document +(e.g. <path>/doc/${LANG}/</path>). If you are writing a guide that uses the +<c>guide</c> or <c>book</c> DTD, you may use either +<path>/doc/${LANG}/filename.xml</path> or <path>filename.xml</path>. Generally, +the GDP recommends the former specification. +</p> + +</body> +</section> +<section> +<title>Check links</title> +<body> + +<p> +You <e>must</e> verify that all hyperlinks in your document work. If it is a +translated document, make sure that any links to other translated documents +point to the existing files. +</p> + +</body> +</section> +<section> +<title>Check for tabs</title> +<body> + +<p> +Tabs are absolutely forbidden in GuideXML documents except when required (e.g. +if the document instructs the user to use tabs). To check a document for tabs, +run <c>grep "CTRL+V<TAB>" file.xml</c>. Fix any lines that <c>grep</c> +prints out. +</p> + +</body> +</section> +<section> +<title>Bugzilla</title> +<body> + +<p> +Once you have finished your document, submit it to the Documentation Team using +<uri +link="http://bugs.gentoo.org/enter_bug.cgi?product=Documentation";>Bugzilla</uri>. +You don't have to mention information like platform, <c>emerge info</c> +output, arch, steps to reproduce, etc. If you have a translated document, be +sure to select the <uri +link="http://bugs.gentoo.org/enter_bug.cgi?product=Doc%20Translations";>Doc +Translations</uri> component for your bugs. Also, include a helpful summary +for your translation using the preferred format: "[fr] New translation: +/doc/fr/gnupg-user.xml". Replace <b>[fr]</b> with the two-letter code for your +language. +</p> + +<p> +By default, <mail>[EMAIL PROTECTED]</mail> is the assignee of your bug; +there's no need to change the assignee field. +</p> + +<p> +Attach files and patches to the bug using the "plain text (text/plain)" +selection. Do <e>not</e> select "XML source (application/xml)", even if you +are submitting a <path>.xml</path> file. Patches should have the "Patch" option +checked. Do not submit tarballs full of documents; attach each document and +patch individually. +</p> + +</body> +</section> +</chapter> + +<chapter> <title>Commonly or Dangerous Made Mistakes</title> <section> <title>Forgetting the all-arch-aspect of the Gentoo Handbook</title> @@ -442,10 +520,17 @@ <body> <p> -Conforming the policy, you <e>must</e> bump a version/date when you make certain -changes (most actually). Although the version is less important (SwifT will -still kill you if you forget it) the date tells our users when the document was -altered for the last time. +Conforming to the policy, you <e>must</e> bump a version/date when you make +certain changes (most actually). Although the version is less important (SwifT +will still kill you if you forget it) the date tells our users when the +document was last modified. +</p> + +<p> +If you are making a <e>content</e> change to a document (such as instructions, +code examples, etc.), then you must increment the version. For +<e>non-content</e> changes (e.g. typo or GuideXML fixes), version bumping is +usually unnecessary. </p> <p> -- [email protected] mailing list
