The Mobile
Broadband Standard

GPRS

EDGE

EDGE+

W-CDMA

UMTS

HSPA

HSPA+

LTE

LTE-Advanced

LTE-Advanced Pro

5G

Writing a new Spec

This page is intended to form a beginner's guide tothe role of a delegate in 3GPP working groups, in particular those who have elected to be the editor – "rapporteur" in 3GPP parlance – of a Technical Specification or Technical Report. The information offered here is as by way of a supplement to the formal 3GPP drafting rules given in TR 21.801, which you are fervently recommended to read as well.

 

Congratulations, you have volunteered (or been volunteered) to be rapporteur for a new TS or TR.  We will refer to TSs and TRs collectively as "Specs", except where there is an important distinction to be made.

Why are you called "rapporteur" rather than "editor"? The word "rapporteur" has been used for a long time in international standardization circles, particularly the ITU. It is a French word meaning literally "reporter", and therein lies the clue: you are required not only to draft the Spec, but also to act as a centre of technical knowledge on it, to whom other 3GPP delegates can pose technical questions and propose modifications. You must also be prepared to respond to questions from the wider community including those uninvolved with 3GPP. And depending on the habits of your working group and TSG, you may also be required to provide regular written status updates on the progress of the draft.


How to start

So, start by downloading the stock TS or TR skeleton document from the 3GPP file server and saving it on your PC. You can download it using either FTP or HTTP

infoDO NOT re-use an existing TS or TR as a starting point - you would run the risk of using an old version or worse, a version polluted with foreign styles or erroneous reformatting.

The Spec templates are in Microsoft Word version 2000 format, i.e. .doc files.

info Although you will probably be using a later version of Word, we strongly recommend you retain the .doc format for your draft Spec, rather than Word's later .docx format.

(There is a reason for retaining the .doc format: the .docx format does not support certain features of the .doc format, in particular the Equation Editor, which is very widely used in 3GPP Specs, especially those from TSG RAN.  We intend to retain the .doc format for Specs for the foreseeable future. For practical hints on editing documents containing old-style equations, follow this link.)

You are not constrained to use Microsoft Word to edit your Spec: you can use any word processor which can handle the .doc format (both reading and saving).

The skeleton Spec file contains all you need to get started, plus quite a lot which you probably won't need in your final spec, but you can delete that later on.  There is also quite a lot of guidance text, rendered in blue. DO read the guidance text and follow its instructions.  When you have done what a particular element of guidance has done, you should delete the corresponding blue text.

Cover page logo(s)

You will see that the skeleton Spec provides you with several options for which logos to retain on the cover page. Follow the blue guidance text to decide which lines to delete.

Stock text

You will see that the skeleton Spec already includes a certain amount of stock text in, for example, the Foreword, and in clauses 2 and 3. DO NOT modify this stock text in any way.

Structure of your Spec

DO NOT change the structure of the early part of the Spec skeleton, though the unnumbered Introduction clause is optional and if you think there is no need for an introduction, you can delete it.  Clauses 1 (Scope), 2 (References), and 3 (Definitions) must remain - though you might wish to delete the "symbols" subclause 3.2 if you have none, in which case you should renumber the "abbreviations" subclause to avoid leaving a gap.

This brings us to another apparently minor, though actually important point: 3GPP Specs are divided into clauses, and NOT into sections or chapters. This terminology is important when you are referencing particular places in a Spec, be those places in the same Spec or in other Specs.

Clause 4 of the skeleton Spec contains some useful guidance about the use of the various built-in paragraph and character styles.  DO read this text - before you delete it.  Ultimately, the main body of your new Spec will start at clause 4.

Clauses 4 onwards are up to you. Use them to provide the main contents of the Spec.

References

DO list every document which is mentioned in the body of your Spec in clause 2 "References". Follow the format of the examples shown in the skeleton document. Any external document can be referenced except:

  • Documents which are not publicly available
    "Publicly available" means that the document can be downloaded or obtained in paper copy from the document's publishers or bookshop. It need not be free of charge, however it shall not be necessary to join an association, club, or other group which has selective membership in order to obtain the document.
  • Documents not in the English language
  • 3GPP-internal TRs, not intended for transposition by the Organizational Partners (usually numbered xx.8xx or 30.xxx or 50.xxx) *
  • 3GPP TDocs *

The * asterisked * conditions are waived if your Spec is itself a 3GPP-internal TR.

It is strongly recommended that references to any non-3GPP document - for example, an ITU Recommendation or an Internet Draft - be to a specific version (i.e. identified by a particular edition or version, or by publication date). Some TSGs insist on this condition.

If you reference a 3GPP Spec which is not included or intended to be included in the same Release as that of your Spec, you must ensure that the reference indicates the Release in which the document can be found.

DO reference a particular 3GPP Spec (or ITU Recommendation, etc.) DO NOT make a generic reference to an entire series of Specs (or Recommendations, etc). Thus reference, say,
32.401
32.402
32.403
as three separate references, rather than a singe reference to
32.40x series.

One of the duties of a rapporteur is to regularly monitor the state of all external documents referenced from his Spec. If any ceases to be available - for example, is withdrawn by its publisher, or goes permanently out of print, or vanishes from a web site - then the reference must be removed or deleted from your Spec by means of a CR. If the reference gave normative provisions essential to the implementation of your Spec, considerable rework might be required.

DO reference other documents; DO NOT copy text from those documents and include it in your Spec. As sure as eggs is eggs, the other document will one day be revised, and the extract which you have copied into your Spec will no longer accord with that revised document.

The only justifiable exception to the do-not-copy rule is where it is known that the external document is not publicly available (according to the definition above). In this case, it is permissible to copy short exerpts into your Spec - although the text may need editorial revision to ensure it abides by the formal drafting rules, and thus not be a verbatim copy. If it is unavoidable to copy lengthy passages or indeed entire documents, then the best approach to this is to include the original document within the zip file of your spec, and to create an annex in your Spec which explicitly "references" that external document by filename, and indicates that the file can be found within this Spec's zip file. When doing such copying and where the source material is not a 3GPP document, always ensure that no violation of copyright conditions are entailed. If in any doubt, consult your MCC Project Manager, who will investigate and if necessary obtain permission to reproduce the text (or figures, etc). Be aware that this might result in a delay in finalization of your Spec, and in the worst case, permission to reproduce may not be forthcoming, in which case your Spec will have to be redrafted to avoid the copied part. 

By convention, once a Spec is under change control, modifying existing reference numbers by inserting or deleting of references is strongly deprecated.

info It is extremely unlikely that any external document which references your Spec will make any mention of its reference list! - nevertheless, if you were to write a CR proposing to insert a new reference (or delete an existing one) and renumber all the references south of that point in the list, it would be necessary to trawl the entire Spec for mentions of those references, and to renumber them all accordingly: a tedious and error-prone activity.

Hence always add a new reference at the end of the existing list, and if a reference becomes obsolete, leave it in the list, but delete the text and replace it with "void": so that, for example

...
[3] 3GPP TS 32.102: "3G Telecom Management architecture".
[4] 3GPP TS 32.106: "3G Performance Management".
[5] ITU-T Recommendation X.710: "Common management information service definition for CCITT applications".
[6] ITU-T Recommendation X.711: "Common management information protocol specification for CCITT applications".
...

might become

[3] 3GPP TS 32.102: "3G Telecom Management architecture".
[4] 3GPP TS 32.106: "3G Performance Management".
[5] (void)
[6] ITU-T Recommendation X.711: "Common management information protocol specification for CCITT applications".

Bibliography

It may be desirable to provide a list of further reading material, particularly in a TR. DO NOT include this in the References clause, but rather, DO create a Bibliography (informative) annex and list the material there, using the same layout conventions as in the References clause, except that the list will be unnumbered.

Clauses 

As you will have gathered, level 1 clauses are numbered 1, 2, 3, 4, etc, and are to be rendered in style Heading 1. There is no limit to how many clauses your Spec may have, but avoid both excessively long clauses and too fine a granularity.

Many if not most clauses will have subclauses, and those subclauses may well have further subclauses.  Bigger fleas have smaller fleas upon their backs to bite 'em. And smaller fleas have lesser fleas, and so ad infinitum.  Level two clauses must be rendered in style Heading 2, level 3 in Heading 3, and so on.  You can subdivide a clause down to six levels.  (Notice that only the higher levels are listed in the table of contents, which would otherwise become too unwieldy.)  If absolutely necessary, you can go beyond six levels, but for all clause title lines from six onwards, use style H6 (not Heading 6).

For clause numbers, retain the arabic numeral system for all levels.  Do not insert a full-stop at the end of the clause number, and separate the clause number from its title by exactly one tab character.

Avoid "hanging paragraphs" - that is, the paragraphs rendered in red in the hypothetical example below:

2.3   Information transfer

Various message types may be used to transfer information across the interface. The type used depends on the context of the transfer.

Message sets shall be consistent, with no message types shared amongst two or more sets.

2.3.1    Call establishment messages

These messages shall be exchanged between entities to establish a call blah blah blah.

2.3.2   Information exchange messages

These messages shall be exchanged between entities to exchange information between those entities in a circular and auto-tautological manner blah blah blah.

2.4   Some new topic

Blather blah blah blah.

Reference to the hanging paragraphs is ambiguous: if a reference cites clause 2.3 of the above document, does it mean just the two red paragraphs, or does it mean everything below the header for clause 2.3 and above the header for clause 2.4? Thus the following structure should be used, since it is completely unambigous, since reference to clause 2.3 obviously includes all its subclauses, since its entire content consists of subclauses.

2.3   Information transfer

2.3.0   Introduction

Various message types may be used to transfer information across the interface. The type used depends on the context of the transfer.

Message sets shall be consistent, with no message types shared amongst two or more sets.

2.3.1    Call establishment messages

These messages shall be exchanged between entities to establish a call blah blah blah.

2.3.2   Information exchange messages

These messages shall be exchanged between entities to exchange information between those entities in a circular and auto-tautological manner blah blah blah.

2.4   Some new topic

Blather blah blah blah.

Annexes

The main body of your Spec will be followed by at least one annex. Annexes are labelled A, B, C, etc. If you want more than 26 annexes, label the next ones AA, AB, AC, etc.

Use annexes to contain supplementary information or details which if included in the main body would make the Spec too turgid to understand on first reading.  Every annex except the change history (see below) MUST be referred to from somewhere within the main body of the Spec.  Such references set the context of the annexes, which would otherwise be floating out of orbit, like uncharted asteroids.

Each annex must be preceded by a hard page break.

Every annex of a TS must be clearly labeled as being either "normative" or "informative".  Try to avoid placing informative text in a normative annex, other than where it is necessary to explain or exemplify a passage of normative content.  Under no circumstances put any normative text in an informative annex.

3GPP TRs which are intended to be "published" by the participating 3GPP Standards Development Organizations can contain no normative text - they are purely informative - so in a TR the template omits the "normative" and "informative" tag on annexes. Note that TSs and TRs use different styles for their annex title lines in order that both are rendered elegantly in the table of contents. Annex title lines in TSs must be in style Heading 8, whilst those in TRs must be in Heading 9.  However, TRs which are designated as internal to 3GPP are often used as temporary placeholders for provisions which will ultimately find themselves moved into normative clauses of TSs; for this reason, the no-normative-text-in-TRs rule is relaxed for internal TRs.  Nevertheless, the intended use should be made clear in the Scope clause of the TR.

See below for more information on normative and informative text.

Note that clause numbers in annexes are to be styled as Heading 1 for A.1, A.2, A.3, etc; Heading 2 for A.1.1, A.1.2, A.1.3, etc; Heading 3 for A.1.1.1, A.1.1.2, A.1.1.3, etc and so on. That is, the annex letter and the dot following it do not count towards the heading level.

Change history

The last annex of your Spec must be entitled "Change history" and must be updated each time you release a new numbered version of the Spec.

During the drafting of a Spec, the text may go through a large number of iterations in the course of a single meeting or even between one meeting and the next.  It might be impractical to update the version number for each and every iteration, and in this case, you must avoid the confusion which could arise where several instances of a Spec might be found, all bearing the same version number, by one or other of the following expedients:

  • removing the cover page and the change history annex from the draft, and providing a TDoc title such as "Revision 3 of TR 36.789 v0.5.1"; or
  • issuing a TDoc in the form of a "text proposal" showing only the updated passages; or
  • issuing a "pseudo-CR" which is similar to a text proposal, but has a CR cover page (though is NOT allocated a CR number).

It is usual to issue a formal new version at or shortly after the end of a working group meeting, when you, the rapporteur, have incorporated all the text changes in all the draft CRs or text proposals agreed during the meeting. When issuing a new version, indicate the date that this version was created (and not the date it was presented to the WG or the date it was distributed by email, etc.).

Figures, tables, notes, examples, equations

Your Spec will probably need to include at least some of these elements - a picture is worth a thousand words - and a common approach is needed throughout your Spec.

Each figure and table must be numbered, with a separate number series used for each. Two approaches to numbering are in common use:

  • continuous numbering from start to finish - i.e. 1, 2, 3, 4, 5, ...
  • clause-based numbering, where each clause or major subclause has its own numbering series, e.g. 4.3-1, 4.3-2, 4.3-3, 6.2-1, 6.2-2, 10.7-1, 10.7-2, ...

You may choose the approach you prefer, but do adopt the same approach for numbering both figures and tables, do not mix the two systems.

Figures have their number and title below the figure; the figure must be in style TH and the caption line containing the number and title in style TF. Tables have their caption lines above the table, in style TH.  The text in the body of tables must use styles TAH (heading rows), TAL / TAC / TAR for left-justified / centered / right-justified text for normal rows, and TAN for notes within the frame of the table.

Notes and examples need not be numbered unless there are more than one note or example in a given (sub)clause, in which case those notes should be numbered 1, 2, 3, ... and the series restarted whenever a new clause number is encountered.

For equations, either of the above numbering mechanisms may be used, but it will generally be found useful to number them so that they may be easily referred to from elsewhere in the Spec, or indeed from external Specs. The equation editor of early versions of Word is not compatible with later versions. To edit a TS or TR containing an equation (e.g. for the purpose of creating a Change Request to it) using MS Word version 2007 or later, it is advisable to convert the file to .docx format, perform the necessary edits, and save the modified file back in .doc format.

A note, introduced with the word "Note" and rendered in the special paragraph style "NO" is a formal construct. DO NOT write normative text in a note: in-line notes are always purely informative. However, notes which are in the frame of a figure (normally below the graphic, but always above the caption line) or of a table may contain normative provisions. Such notes must have an explicit reference from somewhere within the figure or table to place them in context.

Editor's notes (which have a dedicated paragraph style) can be used as reminders of things to be added in the Spec at a later date. There are no rules about numbering editor's notes. In principle, when the Spec is 100% conplete, no editor's notes should remain.

Automatic numbering

During drafting, it is likely that clauses and subclauses will need to be added, deleted, or moved from place to place. You might find it useful to use automatic clause numbering to maintain a sequential series of clause numbers. Similarly for figures, tables, notes, etc, Word provides the {seq} field code to make numbering and cross referencing easier and less error-prone. If you do use automatic numbering - and even more so if you don't - keep the numbering logical, consistent, and sequential throughout the Spec.

At the moment when the Spec is approved by the TSG to come under change control, your MCC Project Manager will freeze the clause numbering, and thereafter it must be maintained manually, thus ensuring that existing clause (and figure, table, ...) numbers remain unchanged from version to version and from Relase to Release. Keeping those numbers constant ensures that references to particular clauses (etc) from other Specs will remain correct even as new clauses etc are added to your Spec.

info In fact, the formal drafting rules of TR 21.801 demand that any reference from a 3GPP Spec to another which cites a precise clause (or figure, or table, etc.) must be to a specific version of that referenced Spec. However, this rule was introduced relatively recently, and there are a number of instances where non-specific references do cite a particular clause. Hence the rule mentioned here, that once under change control, restructuring of a Spec is strongly deprecated.

Bullet points

Use bullet points to present lists. A list is much easier to read and digest than a block of continuous text with items separated by commas. An itemized list should use as bullet characters a dash (hyphen), though where there are sub-items, a different character can be used to make the heirarchical level of the item clear. Use numbered items if you need to refer to individual items of the list from elsewhere in the text. The discussion on automatic numbering above applies equally to numbered list items.

Follow the bullet or number character with a tab to ensure correct alignment of the paragraph.

DO use the appropriate paragraph style: B1 for top level, B2 for second level, etc. These styles will automatically indent items from the left margin an appropriate distance according to their level. DO NOT use Normal style then manually indent.

Language and linguistic style

Language

3GPP Specs are to be written in English. All 3GPP business is conducted in English, so anybody offering themselves as a rapporteur will obviously have at least a fair command of the language.

But which English? Most rapporteurs will be familiar with either British English or American English, and these are the varieties you should aim to use.

info You can find comparisons between British English and American English vocabulary on the web, for example:
http://www.englishclub.com/vocabulary/british-american.htm
http://englishonline.free.fr/GrammarAndHelp/UKvsUSVocab/UKvsUSVocab.htm
but few of the commonly differing words are likely to appear in 3GPP Specs.  There are, however, a number of words which are spelt differently in the two varieties, for exmple
  British: routeing       American: routing
  British: signalling       American: signaling
  British: through       American: thru
and many more.  See, for example,
http://en.wikipedia.org/wiki/Comparison_of_American_and_British_English
for a comprehensive, if not necessarily entirely reliable, review of the differences between the languages.

The guidance for a rapporteur is: choose one or the other, and stick to it throughout the entire Spec. This means you may have to adjust text proposals coming from delegates who speak the "other" English before you incorporate them into your document.  It is important that a Spec reads as a uniform document, and not as a collection of contributions having different spellings and linguistic styles.

For further ventilation on the style and vagaries of English, see the ETSI Guide to the use of English.

-ise or -ize ?

A frequent cause of disagreement is the spelling of "-ize" words, such as "standardize". The suffix "-ize" is used to form verbs meaning "bring into some state" specified by the noun or adjective of the stem. Thus "standardize" means to bring into a standard state.

info The suffix "-ize" is derived from the Greek "-izein", which has precisely this meaning. Most British writers educated in the 1960s onwards would use the suffix "-ise": "standardise". Most American writers educated in the 1620s onwards would retain the "-ize" spelling advocated by the Oxford English Dictionary (and, of course, Webster's).  The "-ize" version has the merit of being closer to the original Greek suffix from which it is derived. However, American writers frequently take this too far since many would use "-ize" in verbs and even nouns where the suffix is not related to the above meaning: "compromise" does not mean "bring into a state of comprom" and "revise" does not mean "bring into a state of rev" any more than "advise" means "bring into a state of adv".  Hence for these words, and many more like them, "-ise" is the only logical spelling, deriving in these cases from the past participle of a Latin verb, always spelt with "s". The modern British English writer is spared the thought process of deciding whether to write "-ize" or "-ise" as a function of the etymology of the word by simply using "-ise" for everything, in much the same way as an American English writer would systematically write "-ize" for everything. The most blatant example of the unwarranted "z" in American English is the spelling of "analyze".  Here, the suffix is (or should be) -lyse from the Greek lusis meaning loosening or resolution, and is quite unrelated to "-ize".  The only logical spelling is "analyse".

Omitted articles

Many of the native languages - Finnish, Russian and other Slavic languages, Japanese, Mandarin Chinese, ... - spoken by rapporteurs do not have one or other of the definite article "the" or the indefinite article "a" ("an" before a vowel sound), and these writers may have to rely on their colleagues who are more used to using articles to advise them as to where, in English, they are necessary and when they are not.  Even rapporteurs whose native language does have these articles may find that their usage differs in English.

German punctuation

Actually, this clause relates to all punctuation other than non-standard English punctuation (of which there are at least two schools of thought anyway).  The basic advise is to keep sentences short enough that little or no punctuation (other than the terminal full-stop / period) is needed.  Germans in particular tend to write sentences with very long subjects, and to separate the subject from its verb with a comma.  This is probably a reflection of the need to breath at that point in the sentence, but has the effect of breaking the thought train so that a native English speaker (at least) will probably have to go back to the beginning of the sentence and re-read it mentally omitting that comma.

Example:  Terminal equipment in the powered up but idle state which receives the auto-wake-up command and which is capable of providing visual feedback to the user, shall inform the user of the event.

Curly quotes (Smart quotes)

Disable this feature of your word processor. 3GPP Specs must use "straight" quotes, not the "comma-shaped" characters to which most installations of Word default.

info The rendering of quotation marks is a good indicator as to whether you have inadvertantly changed the default language of your Spec from British English to, say, French guillemets (where the marks will be rendered as small double chevrons: « ») or German Hochkommata (where the leading Gänsefüßchen will be on the base line rather than superscripted: „ ”).

Use double quotation marks, not single, since single quotation marks can be confused for appostrophes. However, if it is unavoidable to nest quotations within quotations, use double marks for the outer ones, and single marks for the inner ones.

Style and idiom

Bearing in mind your international readership, you should keep the style of the language of your Spec as simple as possible, compatible with being clear and unambiguous. Native English speakers, in particular, should take care not to use colloquial words or phrases, or regional idioms. Restrict your vocabulary insofar as possible to words which are likely to be readily understood by the vast majority of your readership.

Specs are to be written in the third person: avoid the pronouns "I" and "we".

Defined terms and abbreviations

If your Spec will make repeated use of a term or an abbreviation, make sure it is defined. The definition must appear in one of:

  • clause 3 of your Spec, or
  • the common 3GPP vocabulary document, TR 21.905, or
  • clause 3 of another 3GPP Spec which you explicitly reference, or
  • a technical document from some third party (such as an ITU Recommendation, an ISO standard, etc), which you explicitly reference.

If you are inventing a new term, first ask yourself whether that term or something very similar is already in use elsewhere in 3GPP.  If so, try to re-use that existing term.  If not, by all means create a new term, but try to make it sufficiently different from any existing term so as to minimize the possibility of confusion between them.

If your new term is likely to used beyond the bounds of your own Spec, consider making it generally available by inserting it in TR 21.905. It will then automatically be available for use within your Spec.

It may seem like a convenience to the reader of your Spec to copy the definition of a term from some other document so it is readily to hand rather than making the reader go off to the other document to search for it; but convenience for the reader is in this case secondary to rigorously correct terminology.  Avoid duplicating a definition which is already to be found in TR 21.905 or in some other 3GPP Spec. If any element of a Spec is replicated, it is certain that, with the passage time, those replicas will mutate and 3GPP will end up with multiple definitions of the same term.  This is obviously undesirable.

If you find that you cannot avoid re-using an existing term but cannot avoid giving it a slightly different meaning in your Spec to that which it has elsewhere, then the definition you include in clause 3 of your Spec will override all other definitions of that term. It might be worth adding in a note below the formal definition that this differs from the same term defined in other Specs.

You should use a defined term to express the same concept each time you use it.  You are not writing a gothic novel or a bed-time story.  You are writing a technical specification or report.  Thus once you have a term with a particular meaning, continue to use that term - and no other - each time you want to express that concept.  If the term is lengthy or complex, you may want to use it in abbreviated form; the same considerations apply to abbreviations as apply to terms.  This practice may make your Spec less readable, but it will more more rigorously technically precise, and faulty logic or ambiguities will be more easily detected.

Normative and informative text

Notwithstanding the foregoing section on Language, you should realize that 3GPP TSs (and to a lesser extent, TRs) are not written in everyday English, but have to observe some conventions of language which are laid down in the formal drafting rules.  Provisions of a Spec (that is to say, passages of text, including figures and tables) are divided into "normative" and "informative" types.

Normative content lays down the requirements of a TS: things which have to be complied with, or it is recommended to comply with, or are possible to comply with.

Informative content gives information or possibly guidance to implementors, but with which it is not necessary (or possible) for equipment to comply with.

Linguistic conventions - verbs

3GPP Specs are not written in "ordinary" English, but in a special "standardese" where certain conventions over auxiliary verbs apply. These conventions can be confusing for some non-native English speakers, whose own languages may have no equivalent to these words.

Mandatory requirements, use "shall": "The equipment shall send a setup message."

info DO NOT follow the IETF convention of using "must" instead of "shall": you shall use shall, you shall not use must.

Recommendations, use "should": "If there is supplementary information to convey, the equipment should send an information message."

Permissions, use "may": "The equipment may send an information message if it wishes to convey status information to the remote equipment."

Describing events which are outside the scope of the Spec, but which need to be taken into consideration, use "will": "The remote equipment will respond with an acknowledge message."

Stating facts, use present indicative: "The parameters are under user control."

Note that in the "recommendation" above, the recommendation was qualified with a condition: "if xxx then yyy". If at all possible, "should" is to be avoided, because, despite being a recommendation, it leaves the choice entirely to the implementer. Far better to specify a rigorous option with a mandatory action, as in "If there is supplementary information to convey, the equipment shall send an information message."

The use of "may" is even woolier, since there is not even a recommendation as to which action is more desirable, to do or not to do. Again, avoid "may" if at all possible.  Note that the negative of "may" is "need not", since "may not" is ambiguous.

Active or passive

Despite very many examples of the contrary, it is usually better to express provisions in the active voice rather than the passive voice, since the former explicitly states who or what is to carry out the action, whereas the latter can leave this unstated and therefore vague.

Thus prefer
"The user equipment shall confirm the receipt of the notification by returning an acknowlege message."
to
"On receipt of the notification, an acknowledge message shall be returned."
In the second example, it is not clear whether the duty of returning the acknowledge message is on the user equipment or on some other entity such as the distant end gateway.

Layout

Use the paragraph and font styles included in the template. It is seldom necessary - and always undesirable - to add new styles, and absolutely forbidden to modify existing styles

You may use italic and bold font for emphasis, but NOT underlining, because this can be confused with revision marking. For the same reason, avoid coloured font. If it is absolutely necessary to use coloured font, DO supply a key so that the reader knows the significance of each colour. But ideally, stick to automatic font colour (normally black).

DO NOT add blank paragraphs or manual page breaks to introduce vertial white space. This is never necessary. If your document throws a page break in an undesirable place, use Word's paragraph properties to, for example, keep all lines of a paragraph together, to enable widow/orphan control, to keep-with-next. In this way, you let Word insert page breaks where necessary, and prevent it from inserting them where undesirable.

DO NOT add vertical white space (leading) using blank paragraphs, except to ensure a clause title line does not immediately follow after a table (where layout can go wrong if this is not done). DO rely on the built-in paragraph styles to govern vertical spacing.

info If paragraphs of style "Normal" have no vertical white space after them, or if they are double-margin justified, it is a sure sign that your Spec does not have the 3GPP styles attached!

Never force a page break before a new clause.

Always force a page break before each new annex.

Use of tradenames, registered trademarks, etc. in Specs

In a word - don't. If at all possible, avoid using registered names or marks in your Spec, and use generic terms instead. If being specific is unavoidable, research the ownership of the tradename or mark, and acknowledge that organization's marks at the start of the Spec, at the foot of page 2.

Table of contents and history table

Each time you edit the draft Spec, remember to refresh the table of contents, and to update the history box at the end of the document to show the meeting at or shortly after which you edited it, the tdoc number (if any) of the new version, the changes wrought (for example by listing the tdocs bringing agreed text proposals to the Spec), and the new version number.

See also the clause above concerning the history table.

Be aware that the page numbers in the table of contents will vary as a function of the paper size (e.g. A4 or Letter) and margin settings on your default or chosen printer. Therefore, do not rely on the page number shown in the table of contents, but rather on the clause number. Never use page numbers in references, either within a Spec or to external 3GPP Specs.

Presentation of draft to TSG for information

More information on this, and the following, procedural aspects can be found in the 3GPP TSG Working Procedures, TR 21.900.

When the working group is agreed that a draft Spec is mature enough - subjectively at least 60% complete - it must be sent to the next TSG meeting for information. This simply gives the document wider visibility, and allows feedback from a wider circle of competence than just the working group delegates. 

The decision that a Spec is ready to be sent for information will be recorded in the meeting report. Send the working-group-agreed text to your MCC Project Manager. The version number will at this point be 0.<something>.<something> (unless it has already been seen by the TSG and is going round the loop again). The Project Manager will now run a final critical eye over your Spec and make any necessary minor improvements which may be necessary to ensure alignment with the 3GPP Drafting Rules (and the guidance on this page).

It sometimes happens that the actual Spec is not available by the end of the meeting, and the rapporteur needs a few days to incorporate all the finally agreed text. Remember that your MCC Project Manager will need additional time to do his final check on the document, and that he may have several Specs to handle in the same time scale. When he has finished his check, he will raise the Spec to version 1.0.0 and send it back to you, the rapporteur.

When presented to the TSG, the Spec must be accompanied by a special cover sheet which indicates the progress made since the previous presentation to the TSG (obviously this part will be left blank the first time it is presented).  It is your responsibility to fill in the cover sheet, and to obtain a TSG tdoc number, and to prepare the tdoc containing your cover sheet plus the MCC-adjusted version of the Spec itself.

It is normally only necessary to present a draft Spec to the TSG for information once. Drafting then resumes in the Working Group. DO make sure you use the version seen by the TSG (normally 1.0.0) as the starting point for further modifications, NOT the version you yourself last edited.

Presentation of draft to TSG for approval

When the working group is agreed that a draft Spec is mature enough - subjectively at least 80% complete - it must be sent to the next TSG meeting for approval.

The steps involved are similar to those above for presenting for information, except that this time, MCC will raise the WG-agreed document to version 2.0.0. The same cover sheet is used in the TSG tdoc, but obviously containing updated information. Pay particular attention to describe in some detail the remaining points of contention or incomplete elements. This text may be used to influence the decision as to whether the work is complete or not (i.e. the percentage completion of the work item concerned).

If the TSG approves the draft Spec, then it will be brought under change control - see below.

If, however, the TSG does not consider the Spec to be ripe enough for approval, it may ask the WG to continue to develop it, and this presentation for approval step will have to be repeated, with the rapporteur producing versions 2.y.z until it is again considered to be ready for approval. Again, the MCC Project Manager must give it a final once-over for conformity to the rules.

Ideally, when a Spec is brought for approval, there should be no, or at least very few, remaining "editor's notes" and "for further study" elements.

Combined information and approval

Although in contradiction of the formal working procedures (TR 21.900), in cases of urgency, a working group may decide to bring a mature Spec for information and for approval at a single TSG meeting, in effect combining the above proceeses. In this case, the Spec will be raised to version 1.0.0 (not 2.0.0), and the TSG may (or may not) immediately approve it to come under change control.

Spec brought under change control

Once a Spec has been approved by the TSG to be brought under change control, the MCC Project Manager will raise it to version x.0.0 where x represents the Release in question. From this point onwards, you, the rapporteur, have no right to edit the Spec. All changes must be done via formal change requests. However, you still have an important role to play in, for example, 

  • assisting your fellow working group delegates in the formulation of CRs;
  • reviewing CRs to your Spec to ensure there are no mutual contradictions amongst them;
  • checking the accuracy of CR implementations by MCC;
  • acting as a contact point and font of all knowlege for technical enquiries concerning the Spec.

 Nevertheless, the bulk of your creative work has reached a successful conclusion so ... congratulations!

And finally ...

You may be interested to read ETSI's A Guide to Writing World Class Standards published (April 2014), a guide to rapporteurs and contributors to standardization.

 


 

Page last reviewed / updated ...
to add a hint on how to edit Specs containing equations [2014-09-24]
to "hide" supplementary informative text in rollover pop-up boxes [2014-05-06]
to incorporate remarks from F Firmin and M Pope [2014-03-20]
clarification on hanging paragraps and clause styles in annexes [2015-01-06]
to correct a spelling mistake [2016-08-05]

John M Meredith 

 

Search
Headlines...
News Feeds