The 3 GPP Seminar All you always wanted

The 3 GPP Seminar All you always wanted to know about 3 GPP … but were too afraid to ask. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 1

The 3 GPP Seminar Module 11 The Drafting Rules – 3 GPP TR 21. 801 Much of the contents of the following slides is based on original material by Keith Drage, Alcatel-Lucent. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 2

Purpose of drafting rules The drafting rules exist to allow: • An aid to clearly expressing the requirements in a defined and unambiguous format. • A structured layout for all specifications to ensure essential information is presented. • A common presentation style for all 3 GPP documents – the “house style”. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 3

Derivation of drafting rules • ISO drafting rules • CEN/CENELEC • ETSI • (two variants) • drafting rules • ANSI drafting rules • As the 3 GPP drafting rules are based on those of other organisations, many of the rules apply in other organisations • ATIS, PTSC © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 • 3 GPP • drafting rules 4

Presentation Use the correct software and correct tools within that software. All documents are edited using MS Word. ® • Set up your version of word in accordance with the rules – above all, use the correct style sheet (3 GPP_70. dot) and skeleton TS or TR, which you can download from the 3 GPP web site. http: //www. 3 gpp. org/ftp/Information/TS_TR_Templates/ … © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 5

Presentation … Always use the appropriate style for the appropriate construct. Never modify the style, either within the style sheet or when used. Only use the styles to apply format to the document. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 6

Correct software See subclause H. 5 of 3 GPP TR 21. 801 (lists other types but these are the important ones). Consult MCC if you need to do something different. • Text: Microsoft Word 2003 or earlier. File compatibility with Word 2003 or earlier shall be retained. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 7

Correct software • Graphics • Micrografx Designer version 3. x or 6. 0 or 7. 0 (preferred) • MS Draw 98 Freeware from Microsoft. The built-in drawing package of Word is not recommended. All other graphical formats are treated as bitmaps which cannot be modified. • MS Visio (file compatibility with version Professional 2003 shall be maintained). For general graphics; the rapporteur shall supply the source file. Not to be used formal SDL diagrams. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 8

Correct software • SDL, MSC: Telelogic* SDT (version supplied by Support Team). Rapporteurs can obtain this software on loan from the 3 GPP Support Team. SDL diagrams can be copy and pasted into Word. Rapporteurs shall supply the source files. * Telelogic AB now owned by IBM © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 9

Load the word templates This MS Word tab in Tools Options … from top toolbar tells you the file location where templates should be on your current installation © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 10

Load the word templates Place the. dot files found at ftp: //ftp. 3 gpp. org/Inf ormation/TS_TR_Te mplates/ there. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 11

Load the word templates If creating a new specification or technical report, start from the document templates freshly downloaded from the site. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 12

3 GPP styles sheets and document templates © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 13

Setting up MS Word in accordance with the rules Requirements of 3 GPP TS 21. 801 (subclause H. 3) • Use centimetres as the preferred unit of measurement. • Do not select "Change 'Straight Quotes' to 'Smart Quotes'" in the Auto. Correct options. • Set Default Tab Stops to 0, 5 cm. During editing you may find it useful to: • Make the style bar visible in normal view. • Make formatting marks visible. • EXAMPLES ON FOLLOWING PAGES ARE SPECIFIC TO ENGLISH VERSIONS OF WORD. The menus mostly appear in the same place with the same layout in other language versions. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 14

Setting preferred unit of measurement In MS Word select Tools Options … from top toolbar Select General tab © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 15

Setting straight quotes In MS Word select Tools Auto. Correct Options … from top toolbar and Auto. Format tab Repeat for Auto. Format As You Type tab You may wish to turn off other automatic “features” while you are doing this! © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 16

Setting default tab positions In MS Word select Format Tabs … from top toolbar (with correct stylesheet may well be the default) © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 17

Viewing formatting marks and style area In MS Word select Tools Options … from top toolbar Select View tab To make formatting marks visible select All To make style area visible place a value Style area width • When editing need View Normal to see this. • Can also be adjusted by dragging the boundary of the style area. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 18

Editing documents Applies to new specifications and technical reports. Applies to CRs proposing to modify specifications and technical reports. Delegates have to get it right, editors and MCC do not have the time to reformat all text in accordance with rules. MCC has one week after end of plenary to implement all change requests. A single WG may have several hundred agreed and approved change requests. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 19

Use styles Heading 1, Heading 2, Heading 3 … in the main body of the document. DO NOT use autonumbering. If you need to go beyond Heading 4 then seriously consider whether the structure of your document is the best. Poor structure makes the document unreadable. Heading 8 / Heading 9 is only used for the heading of an annex – annex headings and styles should be as shown on the right. © 3 GPP 2009 Headings Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 20

References are listed in clause 2 of a TS or TR. The usage in the main text determines whether each reference should be considered normative or informative. Care needs to be taken when citing references: “See TS 21. 543 [6]” carries no normative weight. Contrast this with: “The equipment shall operate as described in TR 34. 975 [7]”: this is a normative statement (even though, in this instance, the referenced document is a TR which cannot in itself contain normative provisions). In the References clause, only list documents which are actually mentioned in the body of the document. Any other background material not specifically cited can be placed in an informative Bibliography annex. When referencing specific versions of a document, it is acceptable to give precise indications of the location in the document which contains the referenced material. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 21

References When referencing specific versions of a document, it is acceptable to give precise indications of the location in the document which contains the referenced material. When referencing non-specific versions of 3 GPP documents, it is usually safe to refer to particular clauses, figures, etc by number, since numbering does not normally change in subsequent versions of the TS or TR. It is not advisable to give precise indications of clause, figure, etc numbers in nonspecific references to documents outside 3 GPP’s control, since there is no guarantee that those numbers will be retained in subsequent versions (unless it is known that the issuing body has such a rule). Only use non-specific references to non-3 GPP documents if you are very certain that subsequent revisions of those documents will not invalidate your reference, eg by removal of the originally referenced material. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 22

Lists Do not autonumber or autobullet, use styles B 1, B 2 etc. Autonumbering can be lost in final conversion to published document, and also there may be references from elsewhere in the text to specific numbers. Make each item in the list read as a continuation of the text in the introduction to the list. Make sure that the normative words DO NOT get repeated, or worse still, do not appear at all, between introduction and each item. Decide whether the list is a set of alternatives where one is performed, or a set of items where all are performed. Make this clear by putting an “; or” or “; and” on the last but one item in the list. DO NOT MIX THESE CONSTRUCTS AT THE SAME LEVEL IN THE SAME LIST. Make precise meaning of “or” clear in the introduction sentence, i. e. whether it is only one of, or at least one of, or indeed none of. Do not use spaces or SHIFT RETURN formatting lists. Use CTRL TAB for getting correct indent on subsequent paragraph in a list item. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 23

List example © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 24

Normative and informative All text in technical specifications is either normative (i. e. must be complied with) or informative (if I ignore it it does not matter). Normative material can be optional; it is still normative. Main text, figures, tables, notes to figures and tables, normative annexes are all normative. Notes to text and informative annexes are informative. Technical reports are always informative – never normative in themselves – but at some point in the future, text extracted from the TR may become part of a technical specification. Thus it is not uncommon to find what appears to be normative language in a TR. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 25

Drafting normative requirements (1) Need to convey the requirement without ambiguity and in a manner where implementors and test suite designers understand exactly what is required. Normative requirements are distinguished by a set of modal auxiliary verbs (see 3 GPP TR 21. 801 annex E). Do not use these words where you are not trying to express a testable requirement: • Mandatory: shall / shall not. Do not use "must" as an alternative for "shall“. Do not use "may not" instead "shall not" to express a prohibition. • Recommendation: should / should not. A certain course of action is preferred but not required. It is a good idea to explain why the recommendation should be followed, or identify circumstance where it might not be followed. Avoid the phrase “should normally”: this means “should” ! • Optional / Permission: may / need not. • Possibility and capability: can / cannot. • "May" signifies permission expressed by the standard, whereas "can" refers to the ability of a user of the standard or to a possibility open to him. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 26

Drafting normative requirements (2) Keep it simple. These requirements may need to be translated into multiple languages. Make it easy to separate out the requirements for each entity. Keep the requirements for one entity distinct from those of another entity. Use a consistent format, i. e. keep conditional statements either at the end of a sentence or at the start of a sentence. Never do both. Use the active rather than the passive, i. e. “The UE shall perform xxx” rather than “xxx shall be performed by the UE”. This includes subsequent paragraphs – too often the first sentence appears in the active, and then the author changes to the passive in subsequent sentences. Always capture a single requirement rather than two. “The message shall contain xxx” could mean “The sender shall include xxx in the message” or “The receiver shall perform error actions if the message does not contain xxx” or both, and is thus ambiguous. Make sure the actor is always clearly identified. Good practive to make sure always name the actor in the main clause rather than use “it”, e. g. “If the UE xxxx, then the UE shall yyyy” rather than “If the UE xxxx, then it shall yyyy”. Don’t worry too much if your text ends up repeating the same term over and over again, as in the example above. Don’t seek to paraphrase technical terms which have a well understood (and maybe formally defined) meaning. You are neither Tolstoy nor Shakespeare. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 27

Hanging paragraphs DO NOT DO THIS 3. 4 Title Text xxxx 3. 4. 1 Another title Text yyyy 3. 4. 2 Yet another title Text zzzz DO DO THIS 3. 4 Title 3. 4. 1 General Text xxxx 3. 4. 2 Another title Text yyyy 3. 4. 3 Yet another title Text zzzz The blue text in the left hand example is a hanging paragraph. They are precluded because if another piece of text makes a normative reference to 3. 4, does this mean just the blue text, or does it mean the blue text + the red text. In the right hand example, we can refer to the blue text as subclause 3. 4. 1, and to the blue text + the red text as subclause 3. 4. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 28

Tables should be introduced from the text. Table title in style TH and appears at top of table Table contents in styles TAH, TAL, TAC etc Notes to table appear in box at bottom in style TAN. This is the only way of knowing that the note is for the table and not for the text and hence normative. © 3 GPP 2009 Tables Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 29

Figures should be introduced from the text Figure title in style TF and appears at bottom of figure Notes to figure appear between figure and the figure title. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 30

Tables and figures – referencing from the text The publisher of a 3 GPP specification or technical report is allowed to place the tables and figures at any point in the publication where they will fit. It would be legitimate to place all tables and figures at the end of the document as in an academic publication. The only context or relationship of a table or figure to the text is therefore a reference made from the text, e. g. “The relationship between … is described in figure 3. 4. 1. ” Note that in the text “figure” and “table” appear in lower case unless they start a sentence. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 31

Numbering issues (see 3 GPP TR 21. 801 subclause 5. 2) Every attempt shall be made to use continuous numbering. However, if continuous numbering cannot be maintained, a new element may be inserted in existing text using an appropriate alphanumeric designation that does not disturb the existing numbering scheme. This applies to all elements (e. g. clause, subclause, annex, figure, table, note, list). Similarly, an existing element may be deleted and replaced with the term "Void. " to minimize disruption to the numbering scheme. However, the title of the deleted element may be retained. Two issues here: • Maintain consistent numbering between releases • Ensure that any references to specific subclauses, etc either from within the document or from outside the document are maintained. Renumbering restrictions generally imposed around the time the document is frozen, although exceptions can be allowed. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 32

Programming languages and code In general start from style PL as this gives a fixed space font In the language does not treat tabs as spaces, then use spaces to format (this makes it easier to extract the code and either compile it or verify it) © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 33

Programming languages and code Any code to be compiled should be extracted as a separate binary or text file as it will also be published separately (e. g. XML in 24. 604, SDL in 23. 009). © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 34

General issues – spaces DO use non-breaking spaces (°) or hyphens (—) in order to avoid unexpected wrap around between two words and/or numbers (e. g. 50°cm, 1° 000, clause° 6, annex°A, table° 1, figure° 1, TR° 21° 801— 1, etc. ). These characters appear as normal spaces ( ) or hyphens (-) when printed out; DO NOT use the underline attribute, as this causes confusion when revision marks are used; DO NOT put more than one space after a full stop; DO NOT precede comma (, ), semicolon (; ), colon (: ), full stop (. ), question mark (? ) or exclamation mark (!) by spaces; DO NOT use spaces in place of tabs when indentation/alignment is required; this can cause text to be misaligned; 3 GPP uses proportional spacing fonts rather than fixed space fonts. This is the reason for some of the above. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 35

General issues - capitalisation DO NOT unnecessarily use capital letters. English apparently differs from American on this. English uses capitals ONLY for: • Starting new sentences. • Titles (and in standards it is first letter of first word only). • Proper names, e. g. names of people or names of cities. “Mobile equipment” is not a proper name. • Abbreviations. Make sure also that abbreviations are used consistently throughout the document. They should only appear in expanded form on first usage. Do not define abbreviations so that the result becomes technical gobbledegook. Make sure the sentence makes sense when the abbreviation is expanded. Various protocols will impose conventions for the usage of capitals on PDU and parameters to make them distinct – use them consistently, as defined in the original source for that protocol. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 36

General issues – paragraph and character styles In documents controlled by style sheets, character styles are a “bug” rather than an enhancement. Once created they are difficult to remove. MS Word creates character styles if you select part of a paragraph and then change the style. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 37

Creating CRs 1) Open the specification you wish to modify. Make sure you have the current reference version of the specification for the release you wish to create the CR for. 2) Remove the subclauses you DO NOT wish to modify. This leaves the subclauses you do wish to modify. Do not include subclauses that are not modified. 3) Paste the CR cover sheet (from templates area for the meeting) at the top of the open document, and complete the details. 4) Insert some appropriate marker between modified subclauses. 5) Make your modifications with revision marks turned on. 6) Save as some appropriate file name for the change request. § DO NOT paste the clauses to be modified into the CR cover sheet. You will lose the style sheet this way. § DO NOT take a CR from one meeting to another just by changing the header and tdoc number. The reference version will have changed as well. § Do NOT assume that the text in a subclause is the same in two different releases. Rebuild mirror CRs for each release from the beginning. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 38

Hovering over the annotation field (purple in this example) tells you exactly what to put in the cover sheet field. Make sure the cover sheet contains all the information for plenary to understand the reason for creation and therefore approve. Plenary can, and does, reject CRs. © 3 GPP 2009 Creating CRs Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 39

Category A CR category (see 3 GPP TR 21. 900 subclause 4. 6. 2) Meaning Corresponds to a correction to an earlier Release Remarks May be used only if a category F CR has been approved for an earlier release. "Earlier release" means either an earlier major version of the same 3 GPP specification or a major version of the equivalent GSM specification from which the 3 GPP specification was created. If a change to an earlier release affects a section which has a counterpart in a later release, then the corresponding category A CR to the later version(s) shall be presented for approval at the same meeting. B Addition or deletion of feature The new feature is to be added to the Release; the reference is not to the Specification itself. This will normally correspond to an identified Work Item. This category shall not be used for a frozen Release, except for alignment CRs as described below. C Functional modification of feature Any functional modification shall correspond to an identified Work Item. However backward compatibility shall be ensured when the issue has an impact on the UE. This category shall not be used for a frozen Release, except for alignment CRs as described below. D Editorial modifications shall have no impact on an implementation. An editorial modification CR to a frozen Release shall not be permitted. E (not used) F Correction © 3 GPP 2009 Used: 1 to correct an error in the specification (i. e. a clear instruction in the specification which leads to incorrect operation of the system); or 2 to correct an ambiguity in the specification which could lead to different implementations which cannot inter-operate; or 3 (void); or 4 to remedy the incorrect implementation of a previously approved CR; or 5 to correct a misalignment between the specifications (stage 1, stage 2 & stage 3) for a feature or service when not introducing a new function or functional change. Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 40

CR decision status CRs are recorded in a database which can be accessed externally. These are the decision categories recorded in the database. © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 41

For more information visit http: //www. 3 gpp. org Or contact john. meredith@etsi. org © 3 GPP 2009 Mobile. The 3 GPP World Training Congress, Course Barcelona, / Module 19 11 th February 2009 42