aas-specs icon indicating copy to clipboard operation
aas-specs copied to clipboard

Use one sentence per line

Open zrgt opened this issue 7 months ago • 4 comments

Currently we have in our documentation multiple sentences in one line, like: The only thing that cannot be defined in the template itself is the unique ID of the submodel instance itself (it is not identical to the ID of the submodel template), as well as the property values, etc. Templates also define cardinalities, for example whether an element is optional or not. Submodel element lists typically contain more than one element: the template contains an exemplary element template; the other elements can be created by copy/paste from this template.

There is a recommendation from AsciiDoc community to handle the text as a source code and to use one sentence per line.

They list the following advantages by using this technique:

- It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition).
- You can easily swap sentences.
- You can easily separate or join paragraphs.
- You can comment out sentences or add commentary to them.
- You can spot sentences which are too long or sentences that vary widely in length.
- You can spot redundant (and thus mundane) patterns in your writing.
  • Additionally we will get much more clear git diffs

Proposal: Convert current documents to the one sentence per line-format and enforce this standard in all future documents

zrgt avatar Jul 09 '24 09:07 zrgt