My tech writing style(rules)

Buy Me a Coffee☕

<For my tech writings>

Basically:

• My explanation is detailed but concise.
• I use my glossary as a main reference to avoid redundant writing, reusing explanations.
• I use descriptive abbrs, and avoid undescriptive abbrs more for guide text but less for source code:
  • E.g. positional-or-keyword parameter as poskeyparam(descriptive) and as pkp(undescriptive).
• I don't use a hyphen(-) for prefixes:
  • E.g. supertype and subtype but not super-type and sub-type.
• I use lowercase but follow grammar:
  • E.g. "I" but not "i" at everywhere in a sentence.
  • E.g. Parameters but not parameters at the beginning of sentence.
  • E.g. Python interpreter but not python interpreter.

<Specifically for my glossary>

• Optionally, a term:
  • has nested terms to check multiple related terms at once.
  • is with the abbr:
    • The abbrs used for term explanations can often be found with the original terms explained together in the glossary.
• Under the term, its explanations are listed with bullet points:
  • The explanations grammatically connected to their term precede the others.

abbreviation (abbr)

• is a short form of a word or phrase, e.g. NumPy(Numerical Python), PEP(Python Enhancement Proposal) and GIL(Global Interpreter Lock).

glossary

• is a list of the terms which must be alphabetically ordererd:
  • The terms containing symbols and digits must be listed in # section, then may be sorted in Unicode point order.

guide text

• is explanatory text.
• I use the term as the antonym of source code.

source code

• is the human-readable language not compiled yet to a machine-readable language to command machine.
• Comments are also source code.
• I use the term as the antonym of guide text.

term definition

• is the block to explain a term in my glossary.
• is the combination of a term header and body:

  • term header

    • is the beginning section which must have the term optionally followed by the abbr with ():
      • A term must have all-lowercase characters, and be singular without an article if not special.
      • A descriptive and undescriptive abbr must have all lowercase and uppercase respectively if not special.
      • There is the situation where a term is abbreviated, keeping or not keeping its case.

  • term body

    • is the section which has the term explanations and optionally nested term definitions listed with bullet points:
      • The explanations grammatically connected to their term should be at the beginning.
      • Nested term definitions:
        • should be at end.
        • should be related to their term.
        • can be ordered or unordered.

E.g.
 ↓ ↓ Term name (Required) ↓ ↓   ↓ ↓ ↓ ↓ ↓ ↓ ↓ Abbr (Optional)
positional-or-keyword parameter (poskeyparam)              <- Term header
・ is the one to receive a positional or keyword argument. <- Term body
・ E.g. def func(x) -> None: ....                          <- Term body