1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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>
|
