- The absence of a good documentation slows down and even blocks professionals from doing their jobs.
- The turnover ¹ on teams can lead to loose critical informations.
- Writing docs is hard and we need some guide to keep our knowledge safe and usefull.
Everyone on your team! Everyone can benefit from reading a good doc (even the author can forget something) so everyone should give it back by document critical info.
Everything that's not coded! Big decisions, planing, tools, system names, portals, IPs, enviroments, team organograms, client contacts, manual processes...
On cloud! You can use some document specific solution or leverage a file solution or code repository. The colaboration is key part of good docs!
While you do some work! Get some notepad and keep notes during the process. It keeps the critical info at hand and helps you to select what you should document.
-
You should have a single starting point - /single-starting-point
-
You should not dupluplicate information. - /do-not-copy
-
You should have a clear hirearchical structure of documents.
-
You should use simple files.
-
You should use simple text formating to publish information.
-
You should use text hirearchy with: Title, sections, subsections and lists.
-
You should add references to related contents.
-
Do not let a document increase in size, make it in small pieces.
-
You should have a sumary listing all your sources of knowledge.
-
Make your documents accessible to your users.
Short game design document - sbgames.org/sbgames2013/proceedings/artedesign/15-dt-paper_SGDD.pdf
-
Attention Span - en.wikipedia.org/wiki/Attention_span
-
A profile of education journals - researchgate.net/publication/228365620
-
Reading Speed Is Slower Than Previously Thought - digest.bps.org.uk/2019/06/13/
-
Socratic Questioning - unl.edu/gradstudies/connections/socratic-questioning
-
Writing the first draft of your science paper - elsevier.com/connect/writing-a-science-paper-some-dos-and-donts
-
Paper Sizes and Formats Explained - swiftpublisher.com/useful-articles/paper-sizes-and-formats-explained
¹ Number of employees leaving a company