{"id":140,"date":"2016-12-01T18:38:21","date_gmt":"2016-12-01T23:38:21","guid":{"rendered":"http:\/\/npsa.parentreprise.com\/?p=140"},"modified":"2017-01-22T08:22:49","modified_gmt":"2017-01-22T13:22:49","slug":"2016-11-documenting-things","status":"publish","type":"post","link":"https:\/\/kwnpsa.ca\/index.php\/2016\/12\/01\/2016-11-documenting-things\/","title":{"rendered":"2016-12: Documenting Things"},"content":{"rendered":"

Location:<\/strong>\u00a0 The Working Centre 58 Queen Street South, Kitchener, ON (plan)
\nDate:<\/strong> December 12th, 2016
\nTime:<\/strong> 7:00 PM<\/p>\n

Much of our September discussion<\/a> revolved around documentation. How do we ensure it gets written when there are so many other priorities? How is it maintained so it does not go out of date? How do we index it so that it is easy to find the information we need when we need it? What tools have we found most helpful in creating and maintaining documentation? What things are important to document, and what things can be skipped? As always, bring your experiences and questions.<\/p>\n

=====<\/p>\n

(Notes by Martin Edmonds)<\/em><\/p>\n

Best Practices:<\/strong>
\n\u00b7 Create documentation for users: \u201cHow To\u201d & \u201cFAQ\u201d documents on Wiki so it can be self-serve or you can pass on links when users ask questions
\n\u00b7 Consider formats for defining requirements:
\no Consider: security, auditor controls, speed, backups, file permissions
\no Ask client where data coming from
\n\u00b7 Weigh balance between: need for documentation versus the effort that it requires to develop
\n\u00b7 Don\u2019t document same info in multiple places or it is more work to maintain
\no Get data into a structured format that data can be entered once and it will ripple through to every relevant place
\n\u00b7 Too much documentation may never be used; Keep it simple with what is most important
\n\u00b7 Know your audience
\n\u00b7 Videos have advantages, but you can\u2019t scan through or search to find what you want
\no Short instructional video on a specific topics can be helpful
\n\u00b7 Consider security: are multiple levels of access required to documentation
\n\u00b7 Consider paper versus electronic forms of documentation
\n\u00b7 Think about what someone would need and how they would find it, if you are not around to show them.
\n\u00b7 Keep it in a standard place. Don\u2019t keep documentation on your personal computer or account, because other people won\u2019t be able to find it.
\n\u00b7 Keep in a place where you can give access to someone else but is not accessible to people who should not get it
\n\u00b7 Include examples in the documentation
\n\u00b7 Include why you did something (not just what you did)
\n\u00b7 How do we make sure that it is done
\no Make it easy to document
\no Allocate more time to do documentation
\no Set aside time at the end of each day to update documentation based on what you worked on that day
\no Document as you do it<\/p>\n

What to Document<\/strong>
\n\u00b7 Enough to get a person started (in case person with knowledge is no longer available)
\n\u00b7 Overview of where documentation is. (big picture view)
\n\u00b7 Explanation of what is done on repeated basis at certain times (eg. Holiday posting done each year)
\n\u00b7 Document characteristics of users. For example: user expectations, knowledge, tendencies, tolerance for flaws, etc.<\/p>\n

Tools:<\/strong>
\n\u00b7 Word processor is not ideal since the documentation should be structured so that it can be queried
\n\u00b7 Wiki: forces you to think of structure; easy to create new links to new pages; good for collaborative authoring; manages revisions;
\no A wiki is not as simple to use as a word processor, but non-programmers can update document using wiki
\no Using a wiki may discourage some people from commenting because of learning curve
\no Requires a good editor
\no Can preview documentation through wiki
\no Wiki is not great for multiple security levels of access to documentation<\/p>\n

\u00b7 Tools to consider<\/strong>
\no OneNote
\no \u201cRemarkable\u201d use on a tablet for taking notes at a meeting
\no Data Base: such as Access
\no Cloud based: Eg. Google Keep, Google Docs
\no Sharepoint
\n\u00b7 Video and screen capture: eg. SnagIt or Jing or
\n\u00b7 Tools that come with Windows: \u201cRecording Steps\u201d or \u201cSnipping Tool\u201d
\n\u00b7 Word processor or spreadsheet are very easy to use, That is what people know how to use. Those are not ideal, but any documentation is better than no documentation
\n\u00b7 Ticket system which will capture what you did to resolve issue
\n\u00b7 For documenting Network: \u201cLan Sweeper\u201d or \u201cnmap\u201d<\/p>\n","protected":false},"excerpt":{"rendered":"

Location:\u00a0 The Working Centre 58 Queen Street South, Kitchener, ON (plan) Date: December 12th, 2016 Time: 7:00 PM Much of our September discussion revolved around documentation. How do we ensure it gets written when there are so many other priorities? … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[31,14],"tags":[],"class_list":["post-140","post","type-post","status-publish","format-standard","hentry","category-documentation","category-pastmeetings"],"_links":{"self":[{"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/posts\/140","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/comments?post=140"}],"version-history":[{"count":4,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/posts\/140\/revisions"}],"predecessor-version":[{"id":151,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/posts\/140\/revisions\/151"}],"wp:attachment":[{"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/media?parent=140"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/categories?post=140"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/kwnpsa.ca\/index.php\/wp-json\/wp\/v2\/tags?post=140"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}