← Back to branch summary

~ubuntu-core-doc/ubuntu-docs/maverick

« back to all changes in this revision

Viewing changes to generic/styleguide/styleguide-plan.xml

  • Committer: Matthew East
  • Date: 2008-04-03 21:36:44 UTC
  • Revision ID: mdke@ubuntu.com-20080403213644-f1raxxlwe4ng37s6
Smashing up the directory to create new structure discussed on mailing list.
Nothing works.

Show diffs side-by-side

added added

removed removed

Lines of Context:
generic/styleguide/styleguide-plan.xml
1
 
<?xml version="1.0" encoding="UTF-8"?>
2
 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
3
 
        "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
4
 
<article>
5
 
    <title>Document Plan for the Ubuntu Documentation Style Guide</title>
6
 
    <note>
7
 
      <para>If you would like to make changes to this document please go to StyleGuideDiscussion 
8
 
        first. The wiki moin for this plan is generated automatically from styleguide-plan.xml 
9
 
        in the Docteam's Subversion repository.</para>
10
 
    </note>
11
 
    <sect1>
12
 
        <title>Purpose of the Style Guide</title>
13
 
                <itemizedlist>
14
 
                        <listitem>
15
 
                                <para>To help writers communicate clearly.
16
 
                                </para>
17
 
                        </listitem>
18
 
                        <listitem>
19
 
                                <para>To create a consistent style across all documents.
20
 
                                </para>
21
 
                        </listitem>
22
 
                        <listitem>
23
 
                                <para>To create a consistent use of terminology across all
24
 
                                documents.
25
 
                                </para>
26
 
                        </listitem>
27
 
                        <listitem>
28
 
                                <para>To highlight common problems in the use of the English
29
 
                                language, and to provide solutions.
30
 
                                </para>
31
 
                        </listitem>
32
 
                        <listitem>
33
 
                                <para>To help writers write for an international audience,
34
 
                                 including how to write for translation.
35
 
                                </para>
36
 
                        </listitem>
37
 
                        <listitem>
38
 
                                <para>To help writers and editors select the appropriate DocBook
39
 
                                markup.
40
 
                                </para>
41
 
                        </listitem>
42
 
                </itemizedlist>
43
 
        <para>The Ubuntu documentation team needs its own style guide because
44
 
        Ubuntu is unique. Ubuntu is Linux + GNU + Debian + (GNOME and KDE) + 
45
 
        the Ubuntu philosophy. No style guide covers the entire spectrum 
46
 
        of Ubuntu components.</para>
47
 
    </sect1>
48
 
    <sect1>
49
 
        <title>Audience Profile</title>
50
 
        <para>The audience for the Ubuntu Documentation Style guide is the
51
 
        Ubuntu Documentation Team. Although the team's members come
52
 
        from a variety of cultures and backgrounds, they have something in
53
 
        common; the desire to produce high quality documentation.
54
 
        </para>
55
 
        <para>Members of the team are competent writers in the English language, 
56
 
        although English is not the first language for many of them.
57
 
        </para>
58
 
    </sect1>
59
 
    <sect1>
60
 
        <title>Scope of the Style Guide</title>
61
 
        <para>The style guide will contain two main types of information:</para>
62
 
        <orderedlist>
63
 
           <listitem>
64
 
             <para>Topics and situations applicable to Ubuntu documentation but 
65
 
             not covered in other style guides.</para>
66
 
           </listitem>
67
 
           <listitem>
68
 
             <para>Information found in other style guides, but repeated in the 
69
 
             Ubuntu style guide. The purpose of the repeated information is to 
70
 
             provide quicker access to important information.</para>
71
 
           </listitem>
72
 
         </orderedlist>
73
 
     </sect1>
74
 
    <sect1>
75
 
        <title>Overview by Section</title>
76
 
        <orderedlist>
77
 
            <listitem>
78
 
                <para>Preface</para>
79
 
                  <orderedlist>
80
 
                    <listitem>
81
 
                    <para>List of authors</para>
82
 
                    </listitem>
83
 
                    <listitem>
84
 
                    <para>Legal items (copyright, license, history)</para>
85
 
                    </listitem>
86
 
                  </orderedlist>
87
 
            </listitem>
88
 
            <listitem>
89
 
                <para>Introduction</para>
90
 
                  <orderedlist>
91
 
                    <listitem>
92
 
                    <para>The Need for an Ubuntu Documentation Style Guide</para>
93
 
                    </listitem>
94
 
                    <listitem>
95
 
                    <para>Style Guide Precedence</para>
96
 
                    </listitem>
97
 
                  </orderedlist>
98
 
            </listitem>
99
 
            <listitem>
100
 
                <para>Document Structure
101
 
                </para>
102
 
             </listitem>
103
 
            <listitem>
104
 
                <para>Grammar, Punctuation, Spelling, Style, and Word Usage
105
 
                </para>
106
 
            </listitem>
107
 
            <listitem>
108
 
                <para>DocBook Style
109
 
                </para>
110
 
            </listitem>
111
 
            <listitem>
112
 
                <para>Tricky Words
113
 
                </para>
114
 
            </listitem>
115
 
            <listitem>
116
 
                <para>Writing for an International Audience
117
 
                </para>
118
 
            </listitem>
119
 
            <listitem>
120
 
                <para>Terminology</para>
121
 
                  <orderedlist>
122
 
                    <listitem>
123
 
                    <para>General</para>
124
 
                    </listitem>
125
 
                    <listitem>
126
 
                    <para>GUI Terms</para>
127
 
                    </listitem>
128
 
                    <listitem>
129
 
                    <para>User Actions</para>
130
 
                    </listitem>
131
 
                  </orderedlist>
132
 
            </listitem>
133
 
            <listitem>
134
 
                <para>Stylesheet
135
 
                </para>
136
 
            </listitem>
137
 
             <listitem>
138
 
                <para>Reference Materials
139
 
                </para>
140
 
            </listitem>
141
 
       </orderedlist>
142
 
    </sect1>
143
 
    <sect1>
144
 
        <title>Style Guide Creation Process</title>
145
 
           <sect2>
146
 
             <title>Planning Phase</title>
147
 
           <para>Planning begins on April 20, 2005. During the planning phase, the 
148
 
            style guide's structure is created with input from the Ubuntu
149
 
            Documentation Team and with reference to existing style guides. 
150
 
            The planning phase ends on May 31.</para>
151
 
           <para>The phase includes: </para>
152
 
            <itemizedlist>
153
 
            <listitem>
154
 
            <para>an announcement on the ubuntu-doc mailing list</para>
155
 
            </listitem>
156
 
            <listitem>
157
 
            <para>creation of the StyleGuidePlan wiki page</para>
158
 
            </listitem>
159
 
            <listitem>
160
 
            <para>creation of the StyleGuideDiscussion wiki page</para>
161
 
            </listitem>
162
 
            <listitem>
163
 
            <para>creation of the style guide directory structure and skeleton
164
 
             DocBook files in the Subversion repository</para>
165
 
            </listitem>
166
 
            </itemizedlist>
167
 
            <para>By May 31, the style guide structure will be finalized. After 
168
 
            May 31, no structural changes will be made to the style guide unless 
169
 
            the proposed change is first discussed on the StyleGuideDiscussion 
170
 
            wiki page or on the ubuntu-doc list, and agreed to by  participants in 
171
 
            the discussion. Non-participation equals approval.</para>
172
 
           </sect2>
173
 
           <sect2>
174
 
             <title>Writing and Development Phase</title>
175
 
           <para>The writing phase starts on June 1, 2005 and ends on July 31, 
176
 
           2005.</para>
177
 
       </sect2>
178
 
       <sect2>
179
 
           <title>Release</title>
180
 
           <para>The style guide will be released on August 1, 2005. This will 
181
 
           give editors two months before Breezy Badger is released to review the 
182
 
           documentation and bring it into conformance with the style guide.</para>
183
 
           <para>The style guide content will be frozen from August 1 until after 
184
 
           the Breezy Badger release sometime in October 2005. The structure and 
185
 
           content of the style guide must be fairly stable, otherwise there is a 
186
 
           significant risk that it will be ignored by writers and editors.</para>
187
 
       </sect2>
188
 
       <sect2>
189
 
         <title>Post-release Writing and Development Cycle</title>
190
 
           <para>The writing and development cycle will closely follow the Ubuntu 
191
 
           release cycle. Work on the next version of the style guide will start 
192
 
           on the day after Breezy is released, and will continue until two months 
193
 
           before the next release.</para>
194
 
       </sect2>
195
 
    </sect1>
196
 
    <sect1>
197
 
        <title>Version Numbering</title>
198
 
        <para>The version will have two parts and will be in the form n.n. The 
199
 
        first n is the major release, and the second n is the minor release.</para>
200
 
        <para>The initial release (during the first writing and development phase) 
201
 
        will be 0.1. On August 1 (the end of the intial writing and development 
202
 
        phase) the number becomes 1.0 and will stay at 1.0 until after Breezy is 
203
 
        released.</para>
204
 
    </sect1>
205
 
    <sect1>
206
 
        <title>Estimated Page and Graphic Counts</title>
207
 
        <para>There may be a couple of screen captures used to illustrate GUI 
208
 
        terms.</para>
209
 
        <para>The initial release will probably be no more than 25 pages when 
210
 
        printed.</para>
211
 
    </sect1>
212
 
    <sect1>
213
 
        <title>License</title>
214
 
        <para>The Ubuntu Documentation Style Guide will be released under the GNU 
215
 
          Free Documentation License (GFDL) and the Creative Commons Attribution-ShareAlike License (CC-BY-SA)</para>
216
 
    </sect1>
217
 
</article>