kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

On Sat, Jan 02, 2016 at 08:51:31PM +0100, André S. wrote:
> On 02.01.2016 11:45, Marco Ciampa wrote:
> >On Fri, Jan 01, 2016 at 11:03:14PM +0100, André S. wrote:
> >>Hi everyone.
> >>
> >>I worked my way through most of the KiCad documentation during
> >>translation and think it could be improved in one or two places…
> >>Is this the right place to start a discussion on this topic or if
> >>not where would I go?
> >>
> >I think this is the right place. There is not any i18n ml.
> OK, then here I go.
> 
> Terms used:
> 
>  * [software] module: each of KiCad's software modules (Eeschema,
>    Pcbnew, CvPcb…)
> 
> 1, Content
> 
>  * there is much double information (e.g. the general tools/options are
>    explained in almost every software module documentation)
>      o information on tools/options available in every module should be
>        placed in one documentation only (e.g. 'Getting Started' or
>        'KiCad") and then use refer to it [at the top] of every module
>        documentation (i.e. Eeschema, Pcbnew…)
>      o The 'Getting Started' documentation doubles [a lot of]
>        information available in the documentation (Reference Manuals)
>        for the modules of KiCad. I think it could be shortened to the
>        basic usage of each module and then reference to each Reference
>        Manual.
>      o Proposal: get as much information in a single location only and
>        use links where useful and practical.
>      o Hopefully that gets us less information to keep current, easier
>        to maintain, easier to translate

Agree.
> 
> 2. Style
> 
>  * there is a mix of formatting in each documentation (and also
>    throughout all the documents obviously) .
>  * Proposal: establish a style guide (I did not find one) for most
>    common text elements:
>      o headings
>      o paragraphs
>      o fonts (e.g. a sans serif font is much more readable on monitors IMO)

       yes but serif fonts are better for printed matter. So IMHO we
       should use serif for print and print like formats like pdf and epub
       and use sans for HTML format only, if this is easily feasible, 
       or stick with just one font for all formats (suboptimal).

>      o quotations
>      o quotes (when to use a single quote/double quote/typographical
>        quotes)
>      o captions on images and tables
>      o command line examples
>      o literal file names
>      o keyboard input (e.g. “Ctrl+A” vs. “Ctrl-A” vs. <Ctrl>+<A>…)
>      o how to format lists (e.g. bold first list item when an
>        explanation list?)
>      o how to refer to tool icons to klick.
>      o image formats and sizes (in-line icons, images, screenshots…)
>      o …

Agree

> 3. Structure
> 
>  * There are a lot of sentences that are too long. Those are hard to
>    understand and also hard to translate. Aim for shorter sentences,
>    split current long ones into several shorter ones. Keep a sense of
>    instructing sounding "prose".
>  * All Reference Manuals should share an identical structure. e.g.:
>      o Introduction and Overview
>      o description of the GUI elements and menus
>      o basic usage
>      o advanced usage
>      o links to external sources where applicable
>      o …

Agree

> *TL;DR:* slash double information, establish a style guide,
> establish an uniform document structure
> 
> Thanks for reading,
> 
>   André

I absolutely agree. Furthermore improving docs in this way IMHO
accomplish two tasks at once: make KiCad project be considered more a
mature/serious piece of software and help devs/users have a better
"vision" for the whole project.

Why not create a document on this matter? Wait a moment... already done! ;-)

See (and fill) this template:

https://github.com/KiCad/kicad-doc/tree/master/src/doc_writing_style_policy

Regards,

--


Marco Ciampa

I know a joke about UDP, but you might not get it.

+------------------------+
| GNU/Linux User  #78271 |
| FSFE fellow       #364 |
+------------------------+