Documenting Things/Meeting Notes for 2016-12-12
Jump to navigation
Jump to search
Contents
Documenting Things
- Date
- Monday, 12 December 2016
- Event Announcement
- https://www.meetup.com/NetSquared-Kitchener-Waterloo/events/234260323/
Much of our September meeting 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.
Meeting Notes
(Notes by Martin Edmonds)
Best Practices
- Create documentation for users: “How To” & “FAQ” documents on Wiki so it can be self-serve or you can pass on links when users ask questions
- Consider formats for defining requirements:
- Consider: security, auditor controls, speed, backups, file permissions
- Ask client where data coming from
- Weigh balance between: need for documentation versus the effort that it requires to develop
- Don’t document same info in multiple places or it is more work to maintain
- Get data into a structured format that data can be entered once and it will ripple through to every relevant place
- Too much documentation may never be used; Keep it simple with what is most important
- Know your audience
- Videos have advantages, but you can’t scan through or search to find what you want
- Short instructional video on a specific topics can be helpful
- Consider security: are multiple levels of access required to documentation
- Consider paper versus electronic forms of documentation
- Think about what someone would need and how they would find it, if you are not around to show them.
- Keep it in a standard place. Don’t keep documentation on your personal computer or account, because other people won’t be able to find it.
- Keep in a place where you can give access to someone else but is not accessible to people who should not get it
- Include examples in the documentation
- Include why you did something (not just what you did)
- How do we make sure that it is done
- Make it easy to document
- Allocate more time to do documentation
- Set aside time at the end of each day to update documentation based on what you worked on that day
- Document as you do it
What to Document
- Enough to get a person started (in case person with knowledge is no longer available)
- Overview of where documentation is. (big picture view)
- Explanation of what is done on repeated basis at certain times (eg. Holiday posting done each year)
- Document characteristics of users. For example: user expectations, knowledge, tendencies, tolerance for flaws, etc.
Tools
- Word processor is not ideal since the documentation should be structured so that it can be queried
- Wiki: forces you to think of structure; easy to create new links to new pages; good for collaborative authoring; manages revisions;
- A wiki is not as simple to use as a word processor, but non-programmers can update document using wiki
- Using a wiki may discourage some people from commenting because of learning curve
- Requires a good editor
- Can preview documentation through wiki
- Wiki is not great for multiple security levels of access to documentation
- Tools to consider
- OneNote
- “Remarkable” use on a tablet for taking notes at a meeting
- Data Base: such as Access
- Cloud based: Eg. Google Keep, Google Docs
- Sharepoint
- Video and screen capture: eg. SnagIt or Jing or
- Tools that come with Windows: “Recording Steps” or “Snipping Tool”
- 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
- Ticket system which will capture what you did to resolve issue
- For documenting Network: “Lan Sweeper” or “nmap”
