From 233d845f3ed6c975cb24bbd8c999545a546b6601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20S?= Date: Mon, 4 Jan 2016 00:56:27 +0100 Subject: [PATCH 01/10] Update doc_wrinting_style_policy.adoc --- src/doc_writing_style_policy/doc_writing_style_policy.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 9e343017..259abd2a 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -50,8 +50,13 @@ Published on January 3, 2016. [[_style]] == Style +=== Paragraphs +- Each paragraph starts with a capital letter - +=== Lists +- There are only two kinds of lists used: numbered lists, unnumbered lists +- Numbered lists use arabic numbers, roman numbers may be used in indented lists (2nd level) +- Unnumbered lists use bullets for the first level and hyphens for the second level [[_structure]] == Structure From 88cab5cc950f5de22bcd121c9b490e64ba9291e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20S?= Date: Mon, 4 Jan 2016 01:25:34 +0100 Subject: [PATCH 02/10] Update doc_wrinting_style_policy.adoc --- .../doc_writing_style_policy.adoc | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 259abd2a..95de9079 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -50,13 +50,49 @@ Published on January 3, 2016. [[_style]] == Style +=== Medium Dependend Styles +- documentation for electronic display + - uses a sans serif font for better readability + - has top, bottom, left and rigt margin of 2em +- documentation for print + - may use a serif font (though the trend in print also goes sans serif) + - has top, bottom, left and right margin of 2 cm + === Paragraphs +- paragraphs are set in a 12 pt font - Each paragraph starts with a capital letter +=== Headings +- first level headings are set in a 18 pt bold font +- second level headings are set in a 16 pt bold font +- third level headings are set in a 14 pt bold font +- forth and lower level headings are set in a 12 pt bold font +- headings have a padding top and bottom of 12 pt +- headings are numbered with arabic numbers +- headings have no additional indentation relative to the paragraphs + +== Quotes +- double quotes (") are used for +- single quotes (') are used for +- typographic quotes (`` '') are used for + === Lists - There are only two kinds of lists used: numbered lists, unnumbered lists - Numbered lists use arabic numbers, roman numbers may be used in indented lists (2nd level) - Unnumbered lists use bullets for the first level and hyphens for the second level + +=== Tables +- the caption for tables is put above the table +- tables should be kept short enough to fit on a single page for readability +- the header of the table is set in bold font +- the header may get a shaded background (20% grey) + +=== Code Examples +- code examples are command line examples or script examples or similar +- code examples are set in a monospaced font +- the caption for code examples is put above the example +- code examples are displayed with a frame around them and a shaded background (20% grey) + [[_structure]] == Structure From 2ae4b142c0d6c2efd14ee94967998427416f21ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20S?= Date: Mon, 4 Jan 2016 01:29:04 +0100 Subject: [PATCH 03/10] Update doc_wrinting_style_policy.adoc --- .../doc_writing_style_policy.adoc | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 95de9079..b0970b19 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -51,47 +51,47 @@ Published on January 3, 2016. [[_style]] == Style === Medium Dependend Styles -- documentation for electronic display - - uses a sans serif font for better readability - - has top, bottom, left and rigt margin of 2em -- documentation for print - - may use a serif font (though the trend in print also goes sans serif) - - has top, bottom, left and right margin of 2 cm +* documentation for electronic display +** uses a sans serif font for better readability +** has top, bottom, left and rigt margin of 2em +* documentation for print +** may use a serif font (though the trend in print also goes sans serif) +** has top, bottom, left and right margin of 2 cm === Paragraphs -- paragraphs are set in a 12 pt font -- Each paragraph starts with a capital letter +* paragraphs are set in a 12 pt font +* Each paragraph starts with a capital letter === Headings -- first level headings are set in a 18 pt bold font -- second level headings are set in a 16 pt bold font -- third level headings are set in a 14 pt bold font -- forth and lower level headings are set in a 12 pt bold font -- headings have a padding top and bottom of 12 pt -- headings are numbered with arabic numbers -- headings have no additional indentation relative to the paragraphs +* first level headings are set in a 18 pt bold font +* second level headings are set in a 16 pt bold font +* third level headings are set in a 14 pt bold font +* forth and lower level headings are set in a 12 pt bold font +* headings have a padding top and bottom of 12 pt +* headings are numbered with arabic numbers +* headings have no additional indentation relative to the paragraphs == Quotes -- double quotes (") are used for -- single quotes (') are used for -- typographic quotes (`` '') are used for +* double quotes (") are used for +* single quotes (') are used for +* typographic quotes (`` '') are used for === Lists -- There are only two kinds of lists used: numbered lists, unnumbered lists -- Numbered lists use arabic numbers, roman numbers may be used in indented lists (2nd level) -- Unnumbered lists use bullets for the first level and hyphens for the second level +* There are only two kinds of lists used: numbered lists, unnumbered lists +* Ordered lists use arabic numbers, roman numbers may be used in indented lists (2nd level) +* Unordered lists use bullets for the first level and hyphens for the second level for display === Tables -- the caption for tables is put above the table -- tables should be kept short enough to fit on a single page for readability -- the header of the table is set in bold font -- the header may get a shaded background (20% grey) +* the caption for tables is put above the table +* tables should be kept short enough to fit on a single page for readability +* the header of the table is set in bold font +* the header may get a shaded background (20% grey) === Code Examples -- code examples are command line examples or script examples or similar -- code examples are set in a monospaced font -- the caption for code examples is put above the example -- code examples are displayed with a frame around them and a shaded background (20% grey) +* code examples are command line examples or script examples or similar +* code examples are set in a monospaced font +* the caption for code examples is put above the example +* code examples are displayed with a frame around them and a shaded background (20% grey) [[_structure]] == Structure From c0322cfa2e21f421b20b02afa942038ba960e0a1 Mon Sep 17 00:00:00 2001 From: transistorgrab Date: Mon, 4 Jan 2016 22:26:26 +0100 Subject: [PATCH 04/10] Add Style definitions. --- .../doc_writing_style_policy.adoc | 85 +++++++++++++------ 1 file changed, 61 insertions(+), 24 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index b0970b19..13488ae6 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -53,45 +53,82 @@ Published on January 3, 2016. === Medium Dependend Styles * documentation for electronic display ** uses a sans serif font for better readability -** has top, bottom, left and rigt margin of 2em +** has top, bottom, left and right margin of 2em * documentation for print ** may use a serif font (though the trend in print also goes sans serif) ** has top, bottom, left and right margin of 2 cm === Paragraphs -* paragraphs are set in a 12 pt font -* Each paragraph starts with a capital letter +* Paragraphs are set in a 12 pt font. +* Each paragraph starts with a capital letter. === Headings -* first level headings are set in a 18 pt bold font -* second level headings are set in a 16 pt bold font -* third level headings are set in a 14 pt bold font -* forth and lower level headings are set in a 12 pt bold font -* headings have a padding top and bottom of 12 pt -* headings are numbered with arabic numbers -* headings have no additional indentation relative to the paragraphs - -== Quotes -* double quotes (") are used for -* single quotes (') are used for -* typographic quotes (`` '') are used for +* There is only a maximum of four levels of headings that are numbered within a document and may occur in a table of contents. +* Headings are written with capital letters for each noun, verb, adjective and adverb. +* Headings have no additional indentation relative to the paragraphs. +* Headings are numbered with arabic numbers. +* Headings have a padding top and bottom of 12 pt. +* *First level headings* are set in a 18 pt bold font. +** First level headings are numbered concecutively with a single leading number. +** First level headings are used to form chapters. +** Chapters may stand alone without any sections. +* *Second level headings* are set in a 16 pt bold font +** Second level headings are numbered with two numbers seperated by a period. The first number is the number of the chapter, the second number is the concecutive number of the section in that chapter. +** Second level headings are used to form sections. +** Sections may only exist if there is more than one section or it contains more than one subsection. +* *Third level headings* are set in a 14 pt bold font. +** Third level headings are numbered with three numbers seperated by a period. The first number is the number of the chapter, the second number of the section and the third is the concecutive number of the subsection in that section. +** Third level headings are used to form subsections. +** Subsections may only exist if there is more than one subsection or it contains more than one sub-subsection. +* *Forth and lower level headings* are set in a 12 pt bold font. +** Forth level headings are numbered analog to the lower level headings numbering scheme. +** Forth level headings are used to form sub-subsections. +** Sub-subsections may only exist if there is more than one sub-subsection. +* *Fifth level headings* are not numbered and are only used for subheadings e.g. in a chapter with no sections. + +== Quotes and Quotations +* *Single quotes* (') are used for literal names of files and such (e.g. 'netlist.net' or '*.sch'). +* *Double quotes* (") are used for naming things that would literally look different (e.g. "n-dash" vs. '–' or "alpha" vs. 'α' or "netlist file" vs. 'netlist.net'). +* *Typographic quotes* (`` '') are used for inline quotations like ``These are not the diodes you're looking for.''. +* *Block quotes* are used to quote larger amounts of text. +** Block quotes are indented with a padding left and right by 2em. +** Block quotes have a padding top and bottom of 12pt. +** Block quotes have a frame of 2px with a color of 50% grey. === Lists -* There are only two kinds of lists used: numbered lists, unnumbered lists -* Ordered lists use arabic numbers, roman numbers may be used in indented lists (2nd level) -* Unordered lists use bullets for the first level and hyphens for the second level for display +* There are only two kinds of lists in use: ordered (numbered) lists and unordered (unnumbered) lists. +* *Unordered lists* use the bullet character (•) for the first level and hyphens ("n-dash": '–') for the second level for displaying the list elements. +** Unordered lists are the default lists. +** Up to three list levels are allowed. +** When an unordered list is used to explain things, the first item of the list entry (thing to explain) is set in bold font +* *Ordered lists* use arabic numbers, the second level of an ordered list uses lowercase letters +** Ordered lists are used for working instructions and such where the order of steps is important +** More than two list levels are not allowed. === Tables -* the caption for tables is put above the table -* tables should be kept short enough to fit on a single page for readability -* the header of the table is set in bold font -* the header may get a shaded background (20% grey) +* The caption for tables is put above the table, set in bold font and left aligned. +* Captions are useful for reference such as "look on Table 3.2 row 6". +* The caption of tables is numbered with two numbers separated by a period. The first number is the number of the current chapter, the second number is the concecutive number of the table in the current chapter. +** Example: *Table 2.3: Table Example* +* Tables should be kept short enough to fit on a single page for readability. +* The header of the table is set in bold font. +* The lines between table cells are drawn in a grey color (80% grey). + +=== Images +* The caption for images is put below the image, set in bold font and left aligned. +* The caption of images starts with the text 'Image ' is numbered with two numbers separated by a period. The first number is the number of the current chapter, the second number is the concecutive number of the table in the current chapter. +** Example: *Image 1.3: Example Image* +* The image size for online display should not exceed 640 pixels width. +* The image size for online display of tool icons should be between 24x24 and 32x32 pixels. +* Images for print should not contain less than 150 dpi pixel density for high image quality. Screenshots are generally not good for print output. +* Images from screenshots should be made in PNG format, JPG is inferior for this kind of images. + === Code Examples -* code examples are command line examples or script examples or similar +* code examples are command line examples, script examples, text file contents or similar * code examples are set in a monospaced font * the caption for code examples is put above the example -* code examples are displayed with a frame around them and a shaded background (20% grey) +* code examples are displayed with a thin frame around them and a shaded background (≈80% grey) [[_structure]] == Structure From d70b7ae33fef1cc6e50d962f63c0b222bc055fd4 Mon Sep 17 00:00:00 2001 From: transistorgrab Date: Sun, 17 Jan 2016 16:34:17 +0100 Subject: [PATCH 05/10] Add unicode specification, correct wrong quote characters --- .../doc_writing_style_policy.adoc | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 13488ae6..3ec6147a 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -50,6 +50,15 @@ Published on January 3, 2016. [[_style]] == Style + +=== Unicode +The documentation for KiCad uses Unicode for character encoding. Therefore the correct +use of the appropriate Unicode entities is encouraged. +e.g. for ellipses don't use three single dots ('...') but use the correct +unicode ellipsis ('…'). The em-dash ('—') or en-dash ('–') are repesented in +Unicode and not by using multiple hyphens ('-'). The same is true for Umlauts +and other language specific characters. + === Medium Dependend Styles * documentation for electronic display ** uses a sans serif font for better readability @@ -80,7 +89,7 @@ Published on January 3, 2016. ** Third level headings are numbered with three numbers seperated by a period. The first number is the number of the chapter, the second number of the section and the third is the concecutive number of the subsection in that section. ** Third level headings are used to form subsections. ** Subsections may only exist if there is more than one subsection or it contains more than one sub-subsection. -* *Forth and lower level headings* are set in a 12 pt bold font. +* *Forth and higher level headings* are set in a 12 pt bold font. ** Forth level headings are numbered analog to the lower level headings numbering scheme. ** Forth level headings are used to form sub-subsections. ** Sub-subsections may only exist if there is more than one sub-subsection. @@ -89,7 +98,7 @@ Published on January 3, 2016. == Quotes and Quotations * *Single quotes* (') are used for literal names of files and such (e.g. 'netlist.net' or '*.sch'). * *Double quotes* (") are used for naming things that would literally look different (e.g. "n-dash" vs. '–' or "alpha" vs. 'α' or "netlist file" vs. 'netlist.net'). -* *Typographic quotes* (`` '') are used for inline quotations like ``These are not the diodes you're looking for.''. +* *Typographic quotes* („“) are used for inline quotations like „These are not the diodes you're looking for.“. * *Block quotes* are used to quote larger amounts of text. ** Block quotes are indented with a padding left and right by 2em. ** Block quotes have a padding top and bottom of 12pt. From 96a233f6634fc3f1329b5c08aac3080617e39faa Mon Sep 17 00:00:00 2001 From: transistorgrab Date: Fri, 22 Jan 2016 21:02:47 +0100 Subject: [PATCH 06/10] Reorganize some sections, add results from discussion on Github --- .../doc_writing_style_policy.adoc | 140 +++++++++++++----- 1 file changed, 107 insertions(+), 33 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 3ec6147a..5a77563d 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -46,18 +46,42 @@ Published on January 3, 2016. [[_content]] == Content +The documentation for KiCad is done in English. + +=== Wording + +* Generally the documentation is described in a passive style. This means there + are no sentences like "Now I will tell you how KiCad works." This would be + phrased: "KiCad works in the following way." +* The documentation for KiCad will be done in a formal way. Use the appropriate + words to address the reader in a formal way, i.e. do not address the reader + as you would address a friend but as you would address a business partner. +* Working instructions in tutorial passages are written like actual instructions + to the reader, i.e. „To close the window klick on the 'OK' button“ + and not „Klicking on the 'OK' button will close the window.“. [[_style]] == Style === Unicode -The documentation for KiCad uses Unicode for character encoding. Therefore the correct -use of the appropriate Unicode entities is encouraged. -e.g. for ellipses don't use three single dots ('...') but use the correct -unicode ellipsis ('…'). The em-dash ('—') or en-dash ('–') are repesented in -Unicode and not by using multiple hyphens ('-'). The same is true for Umlauts -and other language specific characters. +The documentation for KiCad uses Unicode for character encoding. +Unicode characters should be used where no equivalent AsciiDoc entity exists. +Here is a list of commonly used charakters where an AsciiDoc entity exists (see +also +http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#text-replacement): +* Ellipsis: three dots in a row are translated to … +* Em-Dash: two hyphens in a row are translated to — + +Nonetheless AsciiDoc respects and preserves Unicode characters, so you are free +to use Unicode also. + +=== Translations +Text must be written in the correct language characters. +If there are other conventions for formatting content than in English these +conventions must be used. +For instance English numbers use the '.' as decimal whereas in German the ',' +is used (e.g. '2.54' vs. '2,54'). === Medium Dependend Styles * documentation for electronic display @@ -67,13 +91,15 @@ and other language specific characters. ** may use a serif font (though the trend in print also goes sans serif) ** has top, bottom, left and right margin of 2 cm -=== Paragraphs -* Paragraphs are set in a 12 pt font. -* Each paragraph starts with a capital letter. +=== Titles +* Titles are used only once per document to define the title of the document. +* Titles are centered and set in a 22pt bold font. === Headings -* There is only a maximum of four levels of headings that are numbered within a document and may occur in a table of contents. -* Headings are written with capital letters for each noun, verb, adjective and adverb. +* There is a maximum of only four levels of headings that are numbered within + a document and may occur in a table of contents. +* Headings are written with capital letters for each noun, verb, adjective and + adverb. * Headings have no additional indentation relative to the paragraphs. * Headings are numbered with arabic numbers. * Headings have a padding top and bottom of 12 pt. @@ -82,62 +108,110 @@ and other language specific characters. ** First level headings are used to form chapters. ** Chapters may stand alone without any sections. * *Second level headings* are set in a 16 pt bold font -** Second level headings are numbered with two numbers seperated by a period. The first number is the number of the chapter, the second number is the concecutive number of the section in that chapter. +** Second level headings are numbered with two numbers seperated by a period. + The first number is the number of the chapter, the second number is the + concecutive number of the section in that chapter. ** Second level headings are used to form sections. -** Sections may only exist if there is more than one section or it contains more than one subsection. +** Sections may only exist if there is more than one section or it contains + more than one subsection. * *Third level headings* are set in a 14 pt bold font. -** Third level headings are numbered with three numbers seperated by a period. The first number is the number of the chapter, the second number of the section and the third is the concecutive number of the subsection in that section. +** Third level headings are numbered with three numbers seperated by a period. + The first number is the number of the chapter, the second number of the + section and the third is the concecutive number of the subsection in that + section. ** Third level headings are used to form subsections. -** Subsections may only exist if there is more than one subsection or it contains more than one sub-subsection. +** Subsections may only exist if there is more than one subsection or it + contains more than one sub-subsection. * *Forth and higher level headings* are set in a 12 pt bold font. -** Forth level headings are numbered analog to the lower level headings numbering scheme. +** Forth level headings are numbered analog to the lower level headings + numbering scheme. ** Forth level headings are used to form sub-subsections. ** Sub-subsections may only exist if there is more than one sub-subsection. -* *Fifth level headings* are not numbered and are only used for subheadings e.g. in a chapter with no sections. +* *Fifth level headings* are not numbered and are only used for subheadings + e.g. in a chapter with no sections. + +=== Paragraphs +* Paragraphs are set in a 12 pt font. +* Paragraphs have a bottom padding of 12 pt. +* Each paragraph starts with a capital letter. == Quotes and Quotations -* *Single quotes* (') are used for literal names of files and such (e.g. 'netlist.net' or '*.sch'). -* *Double quotes* (") are used for naming things that would literally look different (e.g. "n-dash" vs. '–' or "alpha" vs. 'α' or "netlist file" vs. 'netlist.net'). -* *Typographic quotes* („“) are used for inline quotations like „These are not the diodes you're looking for.“. +* *Single quotes* (') are used for literal names of files and such (e.g. + 'netlist.net' or '*.sch'). +* *Double quotes* (") are used for naming things that would literally look + different (e.g. "n-dash" vs. '–' or "alpha" vs. 'α' or "netlist file" vs. + 'netlist.net'). +* *Typographic quotes* („“) are used for inline quotations like „These are not + the diodes you're looking for.“. * *Block quotes* are used to quote larger amounts of text. ** Block quotes are indented with a padding left and right by 2em. ** Block quotes have a padding top and bottom of 12pt. ** Block quotes have a frame of 2px with a color of 50% grey. === Lists -* There are only two kinds of lists in use: ordered (numbered) lists and unordered (unnumbered) lists. -* *Unordered lists* use the bullet character (•) for the first level and hyphens ("n-dash": '–') for the second level for displaying the list elements. +* There are only two kinds of lists in use: ordered (numbered) lists and + unordered (unnumbered) lists. +* *Unordered lists* use the bullet character (•) for the first level and + hyphens ("n-dash": '–') for the second level for displaying the list + elements. ** Unordered lists are the default lists. ** Up to three list levels are allowed. -** When an unordered list is used to explain things, the first item of the list entry (thing to explain) is set in bold font -* *Ordered lists* use arabic numbers, the second level of an ordered list uses lowercase letters -** Ordered lists are used for working instructions and such where the order of steps is important +** When an unordered list is used to explain things, the first item of the + list entry (thing to explain) is set in bold font +* *Ordered lists* use arabic numbers, the second level of an ordered list uses + lowercase letters +** Ordered lists are used for working instructions and such where the order of + steps is important ** More than two list levels are not allowed. === Tables * The caption for tables is put above the table, set in bold font and left aligned. * Captions are useful for reference such as "look on Table 3.2 row 6". -* The caption of tables is numbered with two numbers separated by a period. The first number is the number of the current chapter, the second number is the concecutive number of the table in the current chapter. +* The caption of tables is numbered with two numbers separated by a period. The + first number is the number of the current chapter, the second number is the + consecutive number of the table in the current chapter. ** Example: *Table 2.3: Table Example* * Tables should be kept short enough to fit on a single page for readability. * The header of the table is set in bold font. * The lines between table cells are drawn in a grey color (80% grey). === Images -* The caption for images is put below the image, set in bold font and left aligned. -* The caption of images starts with the text 'Image ' is numbered with two numbers separated by a period. The first number is the number of the current chapter, the second number is the concecutive number of the table in the current chapter. +* The caption for images is put below the image, set in bold font and left + aligned. +* The caption of images starts with the text 'Image ' is numbered with two + numbers separated by a period. The first number is the number of the current + chapter, the second number is the concecutive number of the table in the + current chapter. ** Example: *Image 1.3: Example Image* * The image size for online display should not exceed 640 pixels width. -* The image size for online display of tool icons should be between 24x24 and 32x32 pixels. -* Images for print should not contain less than 150 dpi pixel density for high image quality. Screenshots are generally not good for print output. -* Images from screenshots should be made in PNG format, JPG is inferior for this kind of images. +* The image size for online display of tool icons should be between 24x24 and + 32x32 pixels. +* Images for print should not contain less than 150 dpi pixel density for high + image quality. Screenshots are generally not good for print output. +* Images from screenshots should be made in PNG format, JPG is inferior for + this kind of images. === Code Examples -* code examples are command line examples, script examples, text file contents or similar +* code examples are command line examples, script examples, text file contents + or similar * code examples are set in a monospaced font * the caption for code examples is put above the example -* code examples are displayed with a thin frame around them and a shaded background (≈80% grey) +* code examples are displayed with a thin frame around them and a shaded + background (≈80% grey) + +=== Footnotes +* Footnotes must not be used. +** For online display in a long document the footnotes will be out of screen + for the reader and therefore not very helpful. +* Instead use the NOTE syntax of AsciiDoc. These will be displayed different + than normal paragraphs. +** Notes have a note-title set in 14pt bold font that is left aligned. +** Notes are numbered with a trailing number consecutively throughout the + document, i.e. 'Note 1', 'Note 2' etc. +** The body of the note is set below the note-title and left-indented by 3em. +** The note text is set in a italic style. +** Notes have a light grey background. [[_structure]] == Structure From 9391e423ce4c7f03b1b511de94512c7759fb4fe7 Mon Sep 17 00:00:00 2001 From: transistorgrab Date: Sat, 23 Jan 2016 12:53:28 +0100 Subject: [PATCH 07/10] Add structure description, Add explanations for Content and Style --- .../doc_writing_style_policy.adoc | 87 ++++++++++++++++++- 1 file changed, 84 insertions(+), 3 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 5a77563d..717e08a8 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -56,9 +56,13 @@ The documentation for KiCad is done in English. * The documentation for KiCad will be done in a formal way. Use the appropriate words to address the reader in a formal way, i.e. do not address the reader as you would address a friend but as you would address a business partner. + This is especially meant for translations as English mostly does not use such + distinction. (e.g. the English 'Click on X' translates in German either to + 'Klicke auf X' when talking to a friend but to 'Klicken Sie auf X' when + talking to a stranger.) * Working instructions in tutorial passages are written like actual instructions - to the reader, i.e. „To close the window klick on the 'OK' button“ - and not „Klicking on the 'OK' button will close the window.“. + to the reader, i.e. Use „To close the window click on the 'OK' button.“ + but not „Clicking on the 'OK' button will close the window.“. [[_style]] @@ -212,7 +216,84 @@ is used (e.g. '2.54' vs. '2,54'). ** The body of the note is set below the note-title and left-indented by 3em. ** The note text is set in a italic style. ** Notes have a light grey background. +** The space provided by the indentation shows a symbol according to the type + of note, i.e. `NOTE:`, `TIP:`, `IMPORTANT:`, `CAUTION:`, `WARNING:`. These + symbols are defined globally and shared between all documents. [[_structure]] == Structure - +=== Documentation Structure +The KiCad documentation has a structure that provides information on a single +place. Duplicate information in different documents is to be avoided and proper +linking to the document containing the information is mandatory. I.e.: +* There is one document that describes the common GUI elements and all other + documents point to that document. +* There is one document that describes how the component editor works and all + other documents link to that document. + +The whole documentation of KiCad follows the structure shown below whereas each +individual document follows the structure given in <<_document_structure>>. +* KiCad +** This document gives general information about the software suite and + introduction of all software modules. +** Description of the KiCad Manager +** Description of the common GUI elements that are available in every individual + software module. +* Getting Started +** This document describes the basic usage and general workflow of all KiCad + modules to give the user an idea what can be accomplished using KiCad. For + all deeper information will be referenced to the individual Reference + Manuals. +* Eeschema +** This document describes the schematic capture module of KiCad. +* LibEdit +** This document describes the component editor an component library manager + module of KiCad. +* Pcbnew +** This document describes the PCB layout module of KiCad. +* FootprintEditor +** This document describes the footprint editor and footprint library manager + module of KiCad. +* Gerbview +** This document describes the Gerber file viewer module of KiCad. +* Bitmap2component +** This document describes the module of KiCad that generates footprints from + bitmaps. +* Pcb Calculator +** This document describes the module of KiCad that helps with calculations + related to PCB layout and such. +* Pl Editor +** This document describes the module of KiCad that helps setting up frame + references. + +[[_document_structure]] +=== Document Structure + +The documentation (Reference Manual) for all modules of KiCad (Eeschema, +Pcbnew, etc.) shares the same basic structure. This is to give the reader +a better experience when searching for support. + +* Document title +** Copyright information +** Author(s) information +** Feedback information +** Date of creation +* Chapter 1: Introduction +** purpose of this document, what information will be found here +** short description of the software module +* Chapter 2: Installation and Setup +** since all software modules will be installed by installing the main software + package there will be no installation information for the individual modules +** Setup section describes how to set up default and project specifc values for + this module +* Chapter 3: Basic Usage +** This section describes all menu items and the use of all tools available in + individual tool bars. The description is done in a tutorial style following + a simple simple design workflow. +* Chapter 4: Advanced Usage +** This section describes all deeper nested menu settings and special tool + configurations needed for advanced designs (e.g. differential designs). Also + information regarding scripting and other advanced usage is to be found here. +* Chapter 5: References (optional) +** This section provides further references to (external) sources related to the + current topic, e.g. PCB layout guides or schematic style guides. From 04430c0a2d37a67373cf897e04cf084bf6f1359d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20S?= Date: Sat, 23 Jan 2016 13:05:54 +0100 Subject: [PATCH 08/10] Add short sentences instruction to content chapter --- src/doc_writing_style_policy/doc_writing_style_policy.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 717e08a8..b6f1b690 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -63,6 +63,8 @@ The documentation for KiCad is done in English. * Working instructions in tutorial passages are written like actual instructions to the reader, i.e. Use „To close the window click on the 'OK' button.“ but not „Clicking on the 'OK' button will close the window.“. +* Use short sentences. Sentences that span several lines are hard to understand + and also hard to translate. [[_style]] From 65f79ab8c68361bcb3a4c84588dcd8fb6bc13cb1 Mon Sep 17 00:00:00 2001 From: transistorgrab Date: Sun, 31 Jan 2016 19:17:39 +0100 Subject: [PATCH 09/10] add Teminology section and initial entries --- .../doc_writing_style_policy.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index 717e08a8..293658f9 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -64,6 +64,14 @@ The documentation for KiCad is done in English. to the reader, i.e. Use „To close the window click on the 'OK' button.“ but not „Clicking on the 'OK' button will close the window.“. +=== Terminology + +This section collects all definitions for a uniform use of the same terms for +naming things througout all documentation. +* *Software suite*: This term describes KiCad as a whole including + all software modules. +* *Software module*: This term describes each individual software, i.e. + Eeschema, Pcbnew, etc. [[_style]] == Style From f9b40f88d192f814a0eae22894b3b349bd4bd45d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20S?= Date: Tue, 2 Feb 2016 12:54:03 +0100 Subject: [PATCH 10/10] Change formatting for proper Asciidoc rendering fix some typos and misplaced words --- .../doc_writing_style_policy.adoc | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/src/doc_writing_style_policy/doc_writing_style_policy.adoc b/src/doc_writing_style_policy/doc_writing_style_policy.adoc index a1c063cb..14395b81 100644 --- a/src/doc_writing_style_policy/doc_writing_style_policy.adoc +++ b/src/doc_writing_style_policy/doc_writing_style_policy.adoc @@ -70,6 +70,7 @@ The documentation for KiCad is done in English. This section collects all definitions for a uniform use of the same terms for naming things througout all documentation. + * *Software suite*: This term describes KiCad as a whole including all software modules. * *Software module*: This term describes each individual software, i.e. @@ -84,6 +85,7 @@ Unicode characters should be used where no equivalent AsciiDoc entity exists. Here is a list of commonly used charakters where an AsciiDoc entity exists (see also http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#text-replacement): + * Ellipsis: three dots in a row are translated to … * Em-Dash: two hyphens in a row are translated to — @@ -95,7 +97,7 @@ Text must be written in the correct language characters. If there are other conventions for formatting content than in English these conventions must be used. For instance English numbers use the '.' as decimal whereas in German the ',' -is used (e.g. '2.54' vs. '2,54'). +is used (e.g. \'2.54' vs. \'2,54'). === Medium Dependend Styles * documentation for electronic display @@ -150,11 +152,10 @@ is used (e.g. '2.54' vs. '2,54'). * Each paragraph starts with a capital letter. == Quotes and Quotations -* *Single quotes* (') are used for literal names of files and such (e.g. - 'netlist.net' or '*.sch'). +* *Single quotes* (\') are used for literal names of files and such (e.g. \'netlist.net' or \'*.sch'). * *Double quotes* (") are used for naming things that would literally look - different (e.g. "n-dash" vs. '–' or "alpha" vs. 'α' or "netlist file" vs. - 'netlist.net'). + different (e.g. "n-dash" vs. \'–' or "alpha" vs. \'α' or "netlist file" vs. + \'netlist.net'). * *Typographic quotes* („“) are used for inline quotations like „These are not the diodes you're looking for.“. * *Block quotes* are used to quote larger amounts of text. @@ -166,7 +167,7 @@ is used (e.g. '2.54' vs. '2,54'). * There are only two kinds of lists in use: ordered (numbered) lists and unordered (unnumbered) lists. * *Unordered lists* use the bullet character (•) for the first level and - hyphens ("n-dash": '–') for the second level for displaying the list + hyphens ("n-dash": \'–') for the second level for displaying the list elements. ** Unordered lists are the default lists. ** Up to three list levels are allowed. @@ -192,9 +193,9 @@ is used (e.g. '2.54' vs. '2,54'). === Images * The caption for images is put below the image, set in bold font and left aligned. -* The caption of images starts with the text 'Image ' is numbered with two +* The caption of images starts with the text \'Image' is numbered with two numbers separated by a period. The first number is the number of the current - chapter, the second number is the concecutive number of the table in the + chapter, the second number is the concecutive number of the image in the current chapter. ** Example: *Image 1.3: Example Image* * The image size for online display should not exceed 640 pixels width. @@ -222,7 +223,7 @@ is used (e.g. '2.54' vs. '2,54'). than normal paragraphs. ** Notes have a note-title set in 14pt bold font that is left aligned. ** Notes are numbered with a trailing number consecutively throughout the - document, i.e. 'Note 1', 'Note 2' etc. + document, i.e. \'Note 1', \'Note 2' etc. ** The body of the note is set below the note-title and left-indented by 3em. ** The note text is set in a italic style. ** Notes have a light grey background. @@ -243,6 +244,7 @@ linking to the document containing the information is mandatory. I.e.: The whole documentation of KiCad follows the structure shown below whereas each individual document follows the structure given in <<_document_structure>>. + * KiCad ** This document gives general information about the software suite and introduction of all software modules.