My technical writing style

Buy Me a Coffee☕

<For my technical writings>

• Explanation is detailed and concise, basically following grammar:
  • Sometimes, I use "()" just before a word or phrase with no space to show the original form of an abbreviation, to show a sign, to make it more meaningful, etc:
    • E.g. "It's a URL(Uniform Resource Locator).".
    • E.g. "I don't use a hyphen(-).".
    • E.g. "I updated(synchronized) the code.".
  • I use "It's not" instead of "It isn't" and "Cannot" instead of Can't" for clarity.
• Frequently for technical blogs, I use my glossary as a reference to avoid redundant writing, reusing its explanations.
• Basically, I don't use abbreviations but exceptionally, I use:
  • very common ones, e.g. AI, IT, URL and VPN:
    • I may use "()" after them with no space only once.
  • website-specific ones in each technical website, sometimes.
  • descriptive and undescriptive ones in technical blogs if really needed, especially in code areas.
• Sometimes, I don't use a hyphen(-) for prefixes in technical blogs:
  • E.g. supertype and subtype but not super-type and sub-type.
• My approximate ideal length of one post:
  • for technical Q&A websites is:
    • 1 screen long (60 seconds read) and my actual post is the same length.
  • for technical blogs is:
    • 3 screens long (3 minutes read) but my actual post is 5 screens long (5 minutes read):
      • If the length is at least 11 screens long, the post must be separated into two posts to easily edit the post, reducing scroll.
  • for GitHub is:
    • 1 screen long (60 seconds read) as one issue and my actual post is the same length.
    • as short as possible as one pull request and my actual post is the same length.

<Specifically for my glossary>

• Basically, my glossary:
  • is for explanatory texts but not for visual-data sections.
  • has Python related terms but exceptionally has other terms because it's too much to prepare glossaries for them.
• Optionally, a term:
  • has nested terms to check multiple related terms at once.
  • is with its abbreviations (strongly avoided).

abbreviation

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

  • descriptive abbreviation

  • is an abbreviation which is easily recognized as its original form:
    • I create it if really needed and/or the original characters are 30 or more but basically no.
  • E.g. positional-or-keyword parameter as poskeyparam.

  • undescriptive abbreviation
    

  • is an abbreviation which isn't easily recognized as its original form:
    • I create it if really needed but basically no.
  • E.g. positional-or-keyword parameter as PKP.

explanation definition

• is an explanatory section.
• is the combination of a required main explanation, and optional extra-explanation and visual-data section in order:

  • main explanation

  • is a requird concise explanation basically for an visual-data section.
  • ends with ":" if followed by an extra-explanation and/or visual-data section otherwise ends with ".".

  • extra-explanation

  • is an optional, supplementary and detailed explanation with a bullet-pointed note list, basically starting with Notes::
    • A note:
      • can be followed either by a subnote list without Notes: deeper and deeper, or by a visual-data section:
        • A note cannot be followed both by a subnote list and by a visual-data section at the same time.
      • ends with ":" if followed either by a subnote list or by a visual-data section otherwise ends with ".".
      • It's possible that subnotes are or aren't grammatically connected to their supernote.
      • Subnotes grammatically connected to their supernote must be preceded.
  • can be used independently, starting with Notes:, basically at the beginning of a post.

  • visual-data section
    

  • is an optional part which basically can have code areas, images, tables, etc.
  • I use the term as an antonym of explanatory text.

feature specification

• is a detailed explanation of classes, class attributes, function, generics, espetially parameters, etc.
• can be used with explanation definition.

myfunc() can do something special as shown below:

*Notes:
- The 1st  is `value`(Required-Type:[Any](https://docs.python.org/3/library/typing.html#typing.Any)).
- The 2nd argument is `start`(Optional-Default:`0`-Type:`int`):
   - It's a start index(inclusive).
   - Don't use `start=`.
- The 3rd argument is `end`(Optional-Default:`9223372036854775807`-Type:`int`):
   - It's an end index(exclusive).
   - Don't use `end=`.
- Error occurs if `value` doesn't exist.
- `start` and `end` can be signed indices(zero and positive and negative indices).
- Error doesn't occur even if `[start, end)` is out of the range `[The 1st index, The list length)`.

code

• is source code or a general term to cover source and machine code.

  • source code

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

  • machine code

  • is a machine readable language compiled from a human-readable language to command machine.
  • can also be called machine language and binary code but I use machine code because it's suitable as an antonym of source code and code.
  • I use the term as an antonym of source code and code.

  • code area

  • is a source code area.

  • explanatory text

  • is a guide text.
  • I use the term as an antonym of visual-data section.

  • code block

  • is a set of one or more statements after ":" as a body in some statements, e.g. if, for, while statement, etc.

  • code snippet

  • is a small piece of code snipped out from some code.

technical website

• is a general term to cover the websites related to technology, e.g. DEV, GitHub and Stack Overflow.

  • DEV Community (DEV)

  • is a technical blog.

  • technical blog

  • is a website to write technical posts.
  • is less public, making it more personal.

  • technical post

  • is a publication written about technology.

  • GitHub

  • is a website to manage a project which contains source code, documentation, a README, etc.

  • Stack Overflow

  • is a Q&A website which specializes in coding.

writing

• is a gereral term to cover any written contents whether formal or informal, e.g. documents, quick notes and doodles.

  • technical writing

  • is a gereral term to cover writings about technology, e.g. documentation, a glossary in documentation, DEV's blog posts, Stack Overflow's Q&As, GitHub's pull requests and issues, etc.

  • documentation

  • is a set of documents, e.g. technical guides, a glossary, release notes, FAQ, etc.

  • document

  • is a general term to cover formal writings.

  • technical guide

  • is a document to explain how to use a technology.

  • glossary

  • is a document to collect terms which must be alphabetically ordererd:
    • Terms containing symbols and digits must be listed in the # section, then may be sorted in Unicode point order.

  • terminology
    

  • is a set of terms.

  • term
    

  • is a formally defined word or phrase used in a specific field.

  • jargon
    

  • is a formally undefined word or phrase used in a specific field.

  • release notes
    

  • is a document to explain software or service updates.

  • question and answer (Q&A)
    

  • is a communication which people ask questions, then people answer them.

  • frequently asked questions (FAQ)
    

  • is a kind of Q&A which people ask a variety of questions, then staff answer only the frequent ones.

  • note
    

  • is an informal short writing.

  • memorandum (memo)
    

  • is a formal short writing.

term definition

• is an section to explain a term in my glossary.
• is the combination of a required term header and term body, and optional visual-data section in order:
  • A visual-data section follows term body.

  • term header

  • is the required beginning part which must have a term optionally followed by its abbreviations with ():
    • A term must have all-lowercase characters, and be singular without an article if not special:
      • E.g. parameter (param) for a descriptive abbreviation.
      • E.g. Python core (PyCo) for a special descriptive abbreviation.
    • A term can be a link:
      • E.g. assignment statement (assignment statement).
    • To avoid confusion, defining its abbreviations is strongly avoided unless very common and/or special not to be used and even if defined, it's not necessarily used.
    • Basically, its abbreviation should be single but not multiple unless there is a special reason.
    • A descriptive and undescriptive abbreviation must have all lowercase and uppercase respectively if not special:
      • E.g. parameter (param) for a descriptive one.
      • E.g. garbage collecter (GC) for an undescriptive one.
      • E.g. Python core (PyCo) for a special descriptive one.
      • E.g. I haven't seen it yet for a special undescriptive one.
    • There is a situation where a term is abbreviated, keeping or not keeping its case:
      • E.g. parameter (param) keeps case.
      • E.g. Python core (PyCo) and garbage collecter (GC) don't keep case.

  • term body
    

  • is the required main part to explain the term with a bullet-pointed main note list:
    • A main note:
      • except the last note can be followed either by a subnote list or by a visual-data section, and the last note can be followed either by a subnote list and nested term definition list in order, or by a visual-data section:
        • A main note except the last note cannot be followed both by a subnote list and by a visual-data section at the same time.
        • The last note cannot be followed both by a subnote list and nested term definition, and by visual-data section at the same time.
      • ends with ":" if followed either by a subnote list or by a visual-data section otherwise ends with ".":
        • The last main note followed only by a nested term definition list ends with ".".
      • It's possible that main notes are or aren't grammatically connected to their term:
        • Main notes grammatically connected to their term must be preceded.
    • A subnote:
      • can be followed either by a subnote list deeper and deeper, or by a visual-data section.
      • ends with ":" if followed either by a subnote list or by a visual-data section otherwise ends with ".".
      • It's possible that subnotes are or aren't grammatically connected to their supernote:
        • Subnotes grammatically connected to their supernote must be preceded.
    • Nested term definitions:
      • must be at the end.
      • must be related to their superterm and/or one or more nested term definitions themselves.
      • can be ordered or unordered.
      • Deeper-nested term definitions aren't allowed to avoid complexity.

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