Writing style

[transistorgrab]

No description provided.

[transistorgrab]

Here is the pull request for the changes to the writing style policy.

[ciampix]

Before let this document inside the standard docs may we discuss some of these topics? For example this passage:
"...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."
Why should we use these unicode char instead letting asciidoc do it for us?

[transistorgrab]

The thing is: I see this document (writing style) as subject to discussion.
Providing it as "source code" is problematic in this case. Maybe it would be better put into a Wiki-Page or Etherpad – don't know.
If you say that Asciidoc does this too, well ok. It should then be stated in the writing style guide. i.e. "Either use Unicode or use $X. Asciidoc will translate it just fine." I have no knowledge what asciidoc does or not does, since until now I only got involved into translation but not documentation as such. But if there are certain things that are better done in Unicode (maybe e.g. '...' vs. '…') or better in Asciidoc this should also be stated, i.e. "use Unicode for $thing1 but use Asciidoc for $thing2".
I think if you want a certain character displayed and not rely on Asciidoc hopefully translating it correctly Unicode should be the choice.
I think Asciidoc anyway then needs some configuration for some style settings for example headings, margins and such.
I'm open to discussion because I only want to have a clear style guide so that all documentation shares the same style and therefore looks more professionally. And as a place where to look up when in doubt.
(I also created a "style.html" locally to see what the style would look like, but am hesitant to put it on Github since I don't know how to do it in a usable way.)

[ciampix]

Well putting this in wiki or as a git patch does not change the substance that we may discuss about it here or in the mailing list. I do not see it as something problematic. Anyway I was thinking a thing and writing another. I agree that asciidoc could be able to translate some char combination and not others but you have just to try to run it and/or consult the manual pages to figure it out. It is all written, for example here: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions . I do not see this as so important ... I just was wondering why it is better to write the unicode ellipsis and not the three dots directly... since the three dots are actually used in the program menu strings but not the unicode ellipsis...

[transistorgrab]

I put the style test page up here: http://kicadstyle.transistorgrab.de/
just take a look, I'm open for feedback.

[ciampix]

Mmmm seems perfect to me!

[kinichiro]

Hi, @transistorgrab

Here is my thoughts.
I think your PR for "Writing Style" includes 3 topics below.

1. asciidoc conventions especially for KiCad documents
2. Medium dependent sugestions (ex. 12pt, 2cm, 2em, sans serif, 80% grey, ...)
3. Encouragement using Unicode

And your web page explains topic 1. only, right ?

First of all,
I feel topic 2. should be separeted from 1. and 3. in this document
since document writer doesn't control it within asciidoc.
Document writer will just obey topic 1. and 3.

About topic 1. and http://kicadstyle.transistorgrab.de/ ,
I think it is good.
Especially, captions for tables, images and code-examples are good.
Now, captions are applied in some IDF_Exporter document images only.

About topic 2.,
I am not an expert of asciidoc or latex though,
this should be defined by external style sheet or something
that is separated from .adoc file, right ?

About topic 3.,
This is just my personal opinion, I think .adoc file should be plain ascii text as far as it can be.
Asciidoc defines Replacements to replace 3 single dots to ellipsis,
I think this means asciidoc indicates to use ascii chars rather than multibyte chars.

Regards,

[transistorgrab]

Hi @kinichiro,

the website implements all style definitions like size, padding/margins, numbering style via CSS definitions (you can see it in the page source code). Therefore it implements 1. and 2. for one medium: online viewing.

I think for asciidoc writing conventions and style definitions may/must be separated simply for reuse in all KiCad documentation and may also be necessary to render the documentation for different mediums or languages.

Regarding 3. (Unicode) I beg to differ. Especially thinking of translation to non-english languages makes it difficult to write it naturally. If I were to use '"u' for every 'ü' I want to write or other umlauts it would at least be a little discouraging to do translations. And If you think on Russian or Greek translation… I hope I made my point. ;)

I am with you for inter-punctuation like the ellipsis or n- or m-dashes when asciidoc does a good translation on them. I don't know how good it is on these especially when they may clash with other formatting characters used by asciidoc like '_' or '*' or all the quotation formatting constructs.

So if there are safe and approved working asciidoc constructs: using them is mandatory. When there are not safely working constructs: Unicode is encouraged but not mandatory. These should then be named in the writing style guide.

I think this should go also in the writing styles: how to write it in asciidoc to achieve the desired formatting.
Using the asciidoc definitions wherever possible may for instance allow for language specific quotation marks like the French '« »' or other European styles (see here https://en.wikipedia.org/wiki/Quotation_mark#Specific_language_features)

So: we need to define first how the documentation should look like. If that is fixed it needs to be written down how to achieve this style in asciidoc.

I think it should all go in the same document, properly divided into the correct chapters. Maintaining different documents for writing conventions and medium depended formatting seems not necessary to me. I would expect that once the style guide is finished it will be changed not so frequently. And you can point to one document for all contributors so that even if you are "only" a translator you see the whole picture.

[kinichiro]

Hi, About Unicode topic, I also talked about .adoc file. Translated .po file must contain Unicode multibyte chars. If not, I can't translate to Japanese Kanji ;-) I meant that base English .adoc file should be written in plain ascii char, as far as it can be. Document writer edits base English .adoc file. Translator edits language dependent .po file. Designer creates CSS or latex style sheet or something. And I understand your strategy, 1st we should define how doc should look like, next we should explain how each role person should achive to. These 2 steps should be written in one writing style guide (this document). I agree with your way. Thanks for your explanations.

[transistorgrab]

@kinichiro
Ok, now I understand your Unicode proposal. Yes the original English version should only use plain ascii characters where possible.

Do you have any additional style elements that need to be defined? I found in the current documentation some 'Note' blocks that are indented with a "Warning" or "Note" text left of them. These are not defined right now.
The indentation is dependent on the word left of them. I would prefer to have a fixed indentation and the "warning" or "note" above this text block.

We either collect them in this thread and I put them in the file or we need to find another place where to collect all remarks to this document.

[kinichiro]

I was thinking of footnote and contents index.
A footnote is often used in technical docs, but KiCad docs doesn't use it at this time.
PDF and epub have contents index,
and I wonder if style could define contents index or not.

BTW, we can have style definitions for each languages, can't we ?
Some languages would like to use the font other than serif, etc.

For asciidoc conventions,
I would suggest to add description about inline image and image.
KiCad docs are currently using

• inline image tag (image:) for icons in the sentence and images in the table
• image tag (image::) for screen shots

Thanks

[nickoe]

@kinichiro I did not follow all the discussion here, but was triggerd by your comment about foot notes. I guess it would be better to use the NOTE syntax to wirte foot note like information, this because of the different style of renderings we have of the docs (pdf), page based and full page (html).

[kinichiro]

@nickoe I agree. I would like to add KiCad asciidoc conventions DO NOT USE FOOTNOTE.

[transistorgrab]

I updated the file, added your comments into it.

[transistorgrab]

This morning I added some content to the structure chapter. I would like some feedback on this also, will push it right now.

[ciampix]

This last I agree 100% ...

[ciampix]

Hello, I would like to revive this PR and see if it fits our need or not, then merge & close it or simply close it; it is passed enough time... @kinichiro @nickoe @evanshultz and of course all others, please have a say...

[evanshultz]

In general, I really like what @transistorgrab has done here. My vote is to merge it so we have a starting point and then iterate from there.

There are a few things I'd like to submit. Should I do that now (copying the patch above, modifying, submitting PR)? Or should I write down my thoughts as a comment? Or wait for a merge and then patch the merged doc?

[ciampix]

In the near future will be a doc team mailing list to discuss these topics instead of using the PR space that IMHO is wrong for many reasons...

[kinichiro]

Hi, I said all I wanted to suggest in this PR comments space already. So, I'm ok with this. Thanks

[evanshultz]

While I think it's important to have a doc for guidance, and this is a good start, there's still some issues I think are larger topics to be resolved. @ciampix please show us the right forum for this conversation. Thanks!

I'll be happy to put the below into a patch, but here's my rough thoughts from reading the latest PR. (Note that I've not included any grammar/spelling/typo changes/corrections, just conceptual topics.)

Content/Wording
-GSIK should use second person in tutorial section, but use third everywhere else (change)
-Sentences not too short (Dr. Seuss) or too long (change/add)
-Avoid repetitive sentence structure (add)
-Do not write in a subjective manner (add)
-Removed, missing, or deprecated features are not covered (add)
-Place a space between a number and its unit? (add)
-Use British or American spelling? (add)

Content/Terms
-"Pane": a docked window like Layers Manager in GerbView (add)
-"Element": a primitive in a tool, such as text in Eeschema or a line in Pl_editor (add)

Style
-Use arrows for delimiting menu items (add)
-File names are to be in bold (add)
-Bullets are never used with only a single item (add)
-Properly delimit paths in Linux/os x (forward slash) and windows (backslash) (add)

Style/Medium Dependend Styles
-What does 'Medium Dependend Styles" mean? "Dependent"?

Style/Headings
-Sections begin with present participle ("-ing" word, like "Using") (change)
-Only the first letter of each heading is capitalized (change)

Style/Titles + Style/Headings + Style/Paragraphs
-I strongly feel font size, margin, etc. should go elsewhere. Asciidoc will handle this when writing so page rendering is a separate section. This isn't something the writer needs to manually manage.

Quotes and Quotations
-This seems a poor name for this section; maybe it's supposed to be part of Style (change)
-Why no asciidoc features? Like code blocks for Code Examples and admonitions for Footnotes (add)

Quotes and Quotations/Tables
-Tables are to used be rarely and only for truly tabulated data (add)

Structure
-There should not be two subsections with the same name (change)

Structure/Document Structure (second one)
-Here is the top-level structure that I've seen work in existing KiCad docs:
--Title info
--Introduction
--Interface
--Using... (depends greatly on the individual tool in wording and number of subsections)
--Advanced topics (again, could vary greatly depending on the individual tool)
--References (if needed)
-Chapter 2 may have little value
-I think Chapter 3 should be split into an Interface chapter and a Basic Usage chapter (change)

Finally, there are lots of them out there which is probably a better foundation for us, rather than trying to do it alone. I Googled "software document writing style guide" and found seemingly good info in every link on the first page. I plan to read a few style guides and style guide, err, guidance before coming back to this. Following existing industry practice seems like a quite reasonable base for KiCad.

[heitorPB]

Any news here?

[taotieren]

I think the code part should use hack(https://github.com/source-foundry/Hack) font, which can effectively distinguish "0", "o", "i", "1", "l".

[taotieren]

You can refer to the Chinese typesetting guide for content typesetting.（https://github.com/taotieren/chinese-copywriting-guidelines/blob/Simplified/README.en.md）

[taotieren]

I recommend that the fonts used in the manual be open source as much as possible, for example adobe-fonts（https://github.com/adobe-fonts）.