fvanderwielen / linkdump Goto Github PK

This page guides you on how to do technical writing. It sets the standard on what is the expected form of written text
on this documentation site.
You write your text for a good reason. That reason is a clear and specific goal, so use it as a starting point. Only add
detail when it helps your audience to understand your message. Many engineers want to provide as much specific detail as
possible, but this can come at the expense of a reader's understanding and his main point of reading.
Use the following rules when writing and editing your text.

Most Important First

• avoid: Elaborate and give every aspect of the context.
• instead: immediately cut to the chase.

Brevity

• avoid: When deploying the portal together with the orchestrator and site management, it is important to use the correct zip in the CDA command you try to execute
• instead: Check that the CDA command you will execute has the correct zip.

Use words with clear meaning

Do not use words that are ambiguous, vague, complex, abstract, or container words.

• avoid: functionality, utilization, thing,
• instead: feature, use

Remove redundancy

• avoid: The code is stored in SVN. That is where you commit your code. The SVN location is url XYZ.
• instead: Commit your code to SVN at url XYZ.

Be factual

• avoid: subjective statements: A common idea is that CSS is difficult.
• instead: leave it out, and stick to the facts. Fallback: You can have difficulty in writing CSS.

Be specific

• avoid: The code is in SVN.
• instead: The SVN location of the code is XYZ.

Active sentences

• avoid: code must be written to adhere to the coding guidelines.
• instead: you must write code that complies to the coding guidelines.

Use signposting

Signposting sentences explain the structure of your text. They help the reader follow your line of thought, making it easier to read. See for some examples.

For more writing tips and guidelines see:

• http://web.mit.edu/me-ugoffice/communication/technical-writing.pdf
• http://www.library.dmu.ac.uk/Support/Heat/index.php?page=488
• http://en.wikiversity.org/wiki/Technical_writing_style
• http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style
• http://en.wikipedia.org/wiki/Wikipedia:The_perfect_article

node and docker
http://jdlm.info/articles/2016/03/06/lessons-building-node-app-docker.html?r=0
valve varoufakis
http://blogs.valvesoftware.com/economics/why-valve-or-what-do-we-need-corporations-for-and-how-does-valves-management-structure-fit-into-todays-corporate-world/#more-252