diff options
Diffstat (limited to 'zend/documentation/manual/core/en/doc-standard.recommendations.html')
| -rw-r--r-- | zend/documentation/manual/core/en/doc-standard.recommendations.html | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/zend/documentation/manual/core/en/doc-standard.recommendations.html b/zend/documentation/manual/core/en/doc-standard.recommendations.html new file mode 100644 index 0000000..2dec724 --- /dev/null +++ b/zend/documentation/manual/core/en/doc-standard.recommendations.html @@ -0,0 +1,185 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <meta http-equiv="content-type" content="text/html; charset=UTF-8"/> + <title>Recommendations - Zend Framework Manual</title> + +</head> +<body> +<table width="100%"> + <tr valign="top"> + <td width="85%"> + <table width="100%"> + <tr> + <td width="25%" style="text-align: left;"> + <a href="doc-standard.file-formatting.html">Documentation File Formatting</a> + </td> + + <td width="50%" style="text-align: center;"> + <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br /> + <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div> + </td> + + <td width="25%" style="text-align: right;"> + <div class="next" style="text-align: right; float: right;"><a href="project-structure.html">Recommended Project Structure for Zend Framework MVC Applications</a></div> + </td> + </tr> + </table> +<hr /> +<div id="doc-standard.recommendations" class="section"><div class="info"><h1 class="title">Recommendations</h1></div> + + + <div class="section" id="doc-standard.recommendations.editors" name="doc-standard.recommendations.editors"><div class="info"><h1 class="title">Use editors without autoformatting</h1></div> + + + <p class="para"> + For editing the documentation, typically you should not use formal + <acronym class="acronym">XML</acronym> editors. Such editors normally autoformat existing documents + to fit their own standards and/or do not strictly follow the docbook standard. As + examples, we have seen them erase the <acronym class="acronym">CDATA</acronym> tags, change 4 space + separation to tabs or 2 spaces, etc. + </p> + + <p class="para"> + The style guidelines were written in large part to assist translators in recognizing + the lines that have changed using normal <strong class="command">diff</strong> tools. + Autoformatting makes this process more difficult. + </p> + </div> + + <div class="section" id="doc-standard.recommendations.images" name="doc-standard.recommendations.images"><div class="info"><h1 class="title">Use Images</h1></div> + + + <p class="para"> + Good images and diagrams can improve readability and comprehension. Use them + whenever they will assist in these goals. Images should be placed in the + <var class="filename">documentation/manual/en/figures/</var> directory, and be named after + the section identifier in which they occur. + </p> + </div> + + <div class="section" id="doc-standard.recommendations.examples" name="doc-standard.recommendations.examples"><div class="info"><h1 class="title">Use Case Examples</h1></div> + + + <p class="para"> + Look for good use cases submitted by the community, especially those posted in + proposal comments or on one of the mailing lists. Examples often illustrate usage + far better than the narrative does. + </p> + + <p class="para"> + When writing your examples for inclusion in the manual, follow + all coding standards and documentation standards. + </p> + </div> + + <div class="section" id="doc-standard.recommendations.phpdoc" name="doc-standard.recommendations.phpdoc"><div class="info"><h1 class="title">Avoid Replicating phpdoc Contents</h1></div> + + + <p class="para"> + The manual is intended to be a reference guide for end-user usage. Replicating + the phpdoc documentation for internal-use components and classes is not wanted, and + the narrative should be focussed on usage, not the internal workings. In any case, + at this time, we would like the documentation teams to focus on translating the + English manual, not the phpdoc comments. + </p> + </div> + + <div class="section" id="doc-standard.recommendations.links" name="doc-standard.recommendations.links"><div class="info"><h1 class="title">Use Links</h1></div> + + + <p class="para"> + Link to other sections of the manual or to external sources + instead of recreating documentation. + </p> + + <p class="para"> + Linking to other sections of the manual may be done using the + <em class="emphasis"><link></em> tag (to which you must provide link text). + </p> + + <div class="programlisting xml"><div class="xmlcode"><div class="xml" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #009900;"><span style="font-weight: bold; color: black;"><para<span style="font-weight: bold; color: black;">></span></span></span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> "Link" links to a section, using descriptive text: <span style="color: #009900;"><span style="font-weight: bold; color: black;"><link</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000066;">linkend</span>=<span style="color: #ff0000;">"doc-standard.recommendations.links"</span><span style="font-weight: bold; color: black;">></span></span>documentation on</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> links<span style="color: #009900;"><span style="font-weight: bold; color: black;"></link<span style="font-weight: bold; color: black;">></span></span></span>.</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #009900;"><span style="font-weight: bold; color: black;"></para<span style="font-weight: bold; color: black;">></span></span></span></div></li></ol></div></div></div> + + + <p class="para"> + To link to an external resource, use <em class="emphasis"><ulink></em>: + </p> + + <div class="programlisting xml"><div class="xmlcode"><div class="xml" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #009900;"><span style="font-weight: bold; color: black;"><para<span style="font-weight: bold; color: black;">></span></span></span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> The <span style="color: #009900;"><span style="font-weight: bold; color: black;"><ulink</span> <span style="color: #000066;">url</span>=<span style="color: #ff0000;">"http://framework.zend.com/"</span><span style="font-weight: bold; color: black;">></span></span>Zend Framework site<span style="color: #009900;"><span style="font-weight: bold; color: black;"></ulink<span style="font-weight: bold; color: black;">></span></span></span>.</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #009900;"><span style="font-weight: bold; color: black;"></para<span style="font-weight: bold; color: black;">></span></span></span></div></li></ol></div></div></div> + + </div> + </div> + <hr /> + + <table width="100%"> + <tr> + <td width="25%" style="text-align: left;"> + <a href="doc-standard.file-formatting.html">Documentation File Formatting</a> + </td> + + <td width="50%" style="text-align: center;"> + <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br /> + <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div> + </td> + + <td width="25%" style="text-align: right;"> + <div class="next" style="text-align: right; float: right;"><a href="project-structure.html">Recommended Project Structure for Zend Framework MVC Applications</a></div> + </td> + </tr> + </table> +</td> + <td style="font-size: smaller;" width="15%"> <style type="text/css"> +#leftbar { + float: left; + width: 186px; + padding: 5px; + font-size: smaller; +} +ul.toc { + margin: 0px 5px 5px 5px; + padding: 0px; +} +ul.toc li { + font-size: 85%; + margin: 1px 0 1px 1px; + padding: 1px 0 1px 11px; + list-style-type: none; + background-repeat: no-repeat; + background-position: center left; +} +ul.toc li.header { + font-size: 115%; + padding: 5px 0px 5px 11px; + border-bottom: 1px solid #cccccc; + margin-bottom: 5px; +} +ul.toc li.active { + font-weight: bold; +} +ul.toc li a { + text-decoration: none; +} +ul.toc li a:hover { + text-decoration: underline; +} +</style> + <ul class="toc"> + <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li> + <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li> + <li class="header up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></li> + <li><a href="doc-standard.overview.html">Overview</a></li> + <li><a href="doc-standard.file-formatting.html">Documentation File Formatting</a></li> + <li class="active"><a href="doc-standard.recommendations.html">Recommendations</a></li> + </ul> + </td> + </tr> +</table> +</body> +</html>
\ No newline at end of file |