Guida allo stile di scrittura

Obiettivi

User Focused

Il manuale deve essere mantenuto comprensibile dai principianti al montaggio video.

Completo

All features, options and tools of Kdenlive should be described. The manual should provide information on what a feature is, its purpose, and how to use it.

Conciso

Mantieni il testo breve, conciso e pertinente all’argomento che descrivi.

Manutenibile

Write content that will not have to be redone the moment some small change is made in Kdenlive.

Guidelines

Content

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

  • Utilizza il controllo ortografico.

  • Fai attenzione alla grammatica, alla formulazione appropriata e usa un inglese semplice.

  • Pensa a cosa potrebbe essere interessante per un editor video.

  • Describe in general and not in full depth, so you don’t have to adapt the documentation with each new Kdenlive version.

  • Non descrivere bug, nessuno stato attuale.

  • Including why or how an option might be useful. Example Vantaggi delle sequenze.

  • If you are unsure about how a feature works, ask someone else or find out who developed it and ask them.

  • You can add comment (which is not shown in the HTML page, but useful for other editors): .. TODO, How to choose the correct output format and bit rate? Ask advanced user.

Stile

  • Keep sentences short and clear, use verbs and less noun. Resulting in text that is easy to read, objective and to the point. Rule of thumb (but not only!): 20 words or 120 letters per sentence.

  • Be specific: Do not write input device when you mean the mouse.

  • Be entertaining: Each sentence describes something new.

  • Use bold text to highlight: Program names

  • Use italic text to emphasize: Words or phrases as in general writing, Titles when referencing other works, The first use of an unfamiliar word

  • Combined Bold and Italic Text: In restructured text this is only possible with additional code.

Putting a definition first
Sequence
Using sequences you can make your project clearer.

migliore

Sequence
A sequence is basically a timeline.

Then explain what it does and how you can use it. Example: Sequenza

Avoiding the immediate repetition of the term
The Properties Tab
The Properties Tab displays the settings for the effects on the currently selected clip.

migliore

The Properties Tab
The settings for the effects on the currently selected clip are shown the properties tab.
Avoiding the “it is”
Binarize
It is an effect to make he image black and white.

migliore

Binarize
Creates a black and white image.

Immagini

Only .. figure:: should be used to place images.

Use the Kdenlive dark theme when making screenshots.

Usa .webp per le immagini.

Use animated .gif or .mp4 files if that explains the feature/task better.

Try to avoid having a lot of images. Use a single image that shows all of the relevant areas placed at the top of the section. Numbering the features and then explain the features in that order. Like this example.

Ulteriori informazioni

Check the template for how to use the rst commands.