documentation/specification/doc_spec.txt

Document Specification
======================

ajm4, 08/03/2001
pjm2, 19/10/2000

Electronic Standard
-------------------

Standards to adhere to: -

    All documents must be saved as plain text with no more
    than 60 characters per line.

    Documents must be saved with a '.txt' file extension.

    The text file must not contain any HTML tags.
    This is to prevent problems when the file is included
    as the contents on an SHTML page.

    NOTE: The previous point has been relaxed slightly,
    as it made it a bit difficult to display XML tags.
    All documents may now include HTML-style markup, but
    please note that such markup will be displayed on the
    i-scream.org.uk website as written.


Other issues

    If possible, please save the text files in 'Windows'
    format, such that each line is separated by a return
    and also a linefeed character.
    
Publication Standard
--------------------

All documents must use the Word template file that can be
found in CVS:

    CVSROOT:/documentation/i-scream-template.dot

To make use of this template you must set the following.
Click Tools->Options->File Locations and modify the path
of your "Workgroup Templates" to be CVSROOT:/documentation

This should then mean to start a new document, simply click
File->New... and choose the i-scream-template.

1)
The tags <SECTION NAME> and <DOCUMENT NAME> are Word fields
and should NOT be manually changed.  Instead they should be
changed by click File->Properties, where:

    "Title" -> <SECTION NAME>
    "Subject" -> <DOCUMENT NAME>
    
The "Title" and "Subject" fields should be used in ALL areas
where the name of the section or document are needed.

(note, any changes to fields like this must be followed by
 an update of the fields in the document.  To do this, click
 Edit->Select All, then hit F9)

2)
All text should make use of "Styles".  There should be NO
hardcoded text formatting in the document.  If you wish to
change the appearance of a specific style you should change
the document template only.

3)
No changes should be made to the layout of the opening page,
the header or the footer.  Again, all changes should be made
to the template only.

4)
All major changes to a document must have a full revision
entry on the opening page.  This change must also be
verified by a nominated member of the team.

5)
The table of contents must be the first page after the
opening page (including any revsion history).  This should
also NOT be manually edited for a specific document and
again, all changes should be made in the template file ONLY.

Notes :-

To ensure your document is using the latest template, update
CVS and check click Tools->Templates and Add-ins for
information about the attached template.  This should ensure
that all the latest template changes are applied to your
document.  In theory it should just work, but its unclear.

All the above has been tried with Word 2000 *only* some
testing will need to be done to ensure that it is compatible
with Word 97.
Revision:	1.4
Committed:	Sun Mar 11 13:06:29 2001 UTC (23 years, 8 months ago) by pjm2
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Changes since 1.3:	+7 -1 lines
Log Message:	Perhaps it was about time that bit about "no html in text files" was updated...
#	User	Rev	Content
1	tdb	1.1	Document Specification
2			======================
3
4	ajm	1.2	ajm4, 08/03/2001
5	tdb	1.1	pjm2, 19/10/2000
6
7	ajm	1.2	Electronic Standard
8			-------------------
9	tdb	1.1
10			Standards to adhere to: -
11
12			All documents must be saved as plain text with no more
13			than 60 characters per line.
14
15			Documents must be saved with a '.txt' file extension.
16
17			The text file must not contain any HTML tags.
18			This is to prevent problems when the file is included
19			as the contents on an SHTML page.
20
21	pjm2	1.4	NOTE: The previous point has been relaxed slightly,
22			as it made it a bit difficult to display XML tags.
23			All documents may now include HTML-style markup, but
24			please note that such markup will be displayed on the
25			i-scream.org.uk website as written.
26
27	tdb	1.1
28			Other issues
29
30			If possible, please save the text files in 'Windows'
31			format, such that each line is separated by a return
32	ajm	1.2	and also a linefeed character.
33
34			Publication Standard
35			--------------------
36
37			All documents must use the Word template file that can be
38			found in CVS:
39
40			CVSROOT:/documentation/i-scream-template.dot
41
42	ajm	1.3	To make use of this template you must set the following.
43			Click Tools->Options->File Locations and modify the path
44			of your "Workgroup Templates" to be CVSROOT:/documentation
45
46			This should then mean to start a new document, simply click
47			File->New... and choose the i-scream-template.
48
49	ajm	1.2	1)
50			The tags <SECTION NAME> and <DOCUMENT NAME> are Word fields
51			and should NOT be manually changed. Instead they should be
52			changed by click File->Properties, where:
53
54			"Title" -> <SECTION NAME>
55			"Subject" -> <DOCUMENT NAME>
56
57			The "Title" and "Subject" fields should be used in ALL areas
58			where the name of the section or document are needed.
59
60	ajm	1.3	(note, any changes to fields like this must be followed by
61			an update of the fields in the document. To do this, click
62			Edit->Select All, then hit F9)
63
64	ajm	1.2	2)
65			All text should make use of "Styles". There should be NO
66			hardcoded text formatting in the document. If you wish to
67			change the appearance of a specific style you should change
68			the document template only.
69
70			3)
71			No changes should be made to the layout of the opening page,
72			the header or the footer. Again, all changes should be made
73			to the template only.
74
75			4)
76			All major changes to a document must have a full revision
77			entry on the opening page. This change must also be
78			verified by a nominated member of the team.
79
80			5)
81			The table of contents must be the first page after the
82			opening page (including any revsion history). This should
83			also NOT be manually edited for a specific document and
84			again, all changes should be made in the template file ONLY.
85
86			Notes :-
87
88			To ensure your document is using the latest template, update
89	ajm	1.3	CVS and check click Tools->Templates and Add-ins for
90			information about the attached template. This should ensure
91			that all the latest template changes are applied to your
92			document. In theory it should just work, but its unclear.
93	ajm	1.2
94			All the above has been tried with Word 2000 only some
95			testing will need to be done to ensure that it is compatible
96	pjm2	1.4	with Word 97.