User:Thepigdog/Guide to writing technical articles

Writing technical documents, such as on the subjects of mathematics or computer science poses particular challenges.

Getting started

• Consider the reader first.
  • Write always for the reader, to make it as easy as possible to read and understand.
  • Assume that the reader is lazy, but be hard working and diligent on the readers behalf.
  • Answer all the questions the reader could reasonably ask, not just the ones that you want to answer.
• Define a clear subject and scope. Do not allow the document to cover multiple subjects, as this will make it confusing, long and vague.
  • Move unrelated material to other pages, or remove if already described elsewhere.

Writing style

• Technical style
• Active voice
  • Active voice is less ambiguous and is easier to understand.
  • Do not write random statements about it. Instead describe it, with a carefully organised argument that introduces the reader to the subject in the order that they need the information.
• Do not be emotive.
  • Do not persuade the reader. Give only the facts for the reader to decide.
  • Remove almost all adverbs.
• Third person
  • Do not refer to the reader or writer.
  • Do not use the words "one", "we", "I" for this purpose.

When writing even a simple derivation it easy to run out of words. Keep it simple as noise words will be overlooked anyway. Suggested replacements for connecting statements using personal pronouns are,

one obtains	gives
we get	then
one finds	gives the result

Careful organisation can sometimes remove these connectives altogether.

Comprehension and simplicity

• Start at the beginning of the argument
  • Most misunderstandings occur because the reader is missing key information.
  • Attempt to document all you assumptions, even the ones you are not aware of.
• Be prepared to explain the subject to the reader.
  • Do not just give a definition only useful for an expert.
  • This is a general encyclopedia and you should explain to a wide audience.
• Do not let the need for references block you from explaining.
  • Get the references, but do not always use their content in writing.
  • Write content tailored to describe the subject to a general audience.
  • You do not need a link for each line written, if you are faithfully explaining the subject.
• Write for the widest possible audience.
  • This is a general encyclopedia, not a technical encyclopedia.
  • Every statement must be understandable at some level.
• Write from the main principle first.
  • Don't start with the exceptions or the special cases.
• Give examples.
  • An example can make a difficult subject easy by giving concrete meaning to abstract constructs.
• Use as few words as possible so as to clearly convey the factual content.
• Wherever possible remove dependence on the context. Attempt to make every statement, paragraph and section understandable in isolation. Do not assume the document is read from start to end.
• Short sentences and shorter paragraphs (but rarely one sentence)
  • Are easier to understand.
  • Have less ambiguity.
  • Can be more readily understood in isolation from context.

The writer should be invisible

• Write as if you are only describing the subject matter, without ego or personal motive.
• Be factually and unbiased.
• Introduce content for specific reasons, and give the reasons.

Document organisation

Give the document a clear organisation, appropriate for the subject. Start with major topics, and aim for primarily a two level TOC index. Some standard headings are,

• History - Give historical details about when how this was discovered
• Overview - Give background information needed to understand the subject.
• Usage - How is it applied or used
• Definition - Technical definition
• Examples - Examples of how it is applied.
• Discussion - Explanation of the definition, and other matters.
• Implementation - How is it implemented
• See also - related topics
• References

You don't have to use all these major headings. Specific headings for the subject may be better. Aim to build up content and then organise the content by moving content under appropriate headings. This should thin out and reduce the amount of content, in particular sections, allowing you to write more targeted content under each heading,

Editing and review

Re-read the document, looking for statements in the document that feel wrong or are out of context. Ruthlessly modify until the document works, and is all easy to understand. A single unintelligible statement may ruin a whole article by introducing doubt into the readers mind.

• Does the document address a single core purpose and subject?
• Is the document well organised?
• Does the document clearly explain the subject to the reader?
• Is the spelling correct?
• Is the grammar correct?
• Does the document repeat itself. This is almost never allowed except to remind the user near the use of an idea.
• Does every statement feel correct in its context?
• Is every statement clearly intelligible to the reader?

It is the writers duty to write clearly. It is not the readers duty to make extra effort to understand. The reader is always correct in this matter. If the reader does not understand it is the writers fault.

Conduct

• Assume good faith
• Be unfailingly polite.
• Seek first to understand the other persons point of view.
• Assume the other person is correct and knows more than you until proven otherwise.