Slide 1
Slide 1 text
@ryancanhelpyou @WordCampLanc #WCLanc
Oops!.. I Did It Again.
How documentation and journaling
can save you and your team from
making repeat mistakes
Ryan King
Museums and the Web 2018 #MW18
@ryancanhelpyou
Slide 2
Slide 2 text
Good Mornin' !
Slide 3
Slide 3 text
Overview
1. Minding your Mornings
2. Working Workflows
3. Tools, Tips, Techniques
4. Handoffs/Signoffs
Slide 4
Slide 4 text
Introductions
Slide 5
Slide 5 text
Minding your Mornings
1.
Slide 6
Slide 6 text
Tony Robbins
3-part ritual he calls "Priming" :
1. Perform three sets of 30 Kapalbhati Pranayama breaths.
2. Close your eyes and slow your breathing while expressing
gratitude for everything you have.
3. Pray and ask for help, guidance, and strength throughout the
day.
Slide 7
Slide 7 text
Tim Ferriss
1. First, Ferris makes his bed.
2. Next, he meditates for ten to 20 minutes.
3. Next, Ferris does at least 30 seconds of light exercise
followed by some strong tea.
4. He finishes his routine by journaling for five to ten minutes
Slide 8
Slide 8 text
Oprah Winfrey
1. Twenty minutes of meditation
2. Treadmill - fifteen minutes of exercise
3. "Tunes herself in" by going for a walk, listening to music or
preparing a nice meal.
4. Finally, she always concludes her ritual by eating a healthy meal
full of complex carbohydrates, fiber and protein.
Slide 9
Slide 9 text
Barack Obama
1. Start his day in the White House two hours before his first
scheduled event
2. This allowed him to prioritize exercise, an activity he never
missed.
3. Obama doesn't drink coffee. Instead, he opts for green tea and
stays hydrated with orange juice and plenty of water.
4. After his morning exercise and breakfast, Obama would stay
on top of current affairs by reading the New York Times and
watching ESPN.
Slide 10
Slide 10 text
Jocko Willink
1. Heads straight to the gym for a grueling strength workout
which lasts around one hour
2. He finishes his workout with a thirty minute jog, and jumps in
the shower at approximately 6 a.m to get ready for the day
ahead
Slide 11
Slide 11 text
Steve Jobs
1. Make his bed, shower, and then look himself in the mirror:
"If today was the last day of my life,
would I be happy with what I'm about to do today?"
Slide 12
Slide 12 text
Gratitude .
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
Working Workflows
2.
Slide 15
Slide 15 text
http://www.writethedocs.org/guide/
1. A beginner’s guide to writing documentation
2. Documentation Principles & Examples
3. Style Guides
4. Documentation Culture at your Company
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
README
Slide 18
Slide 18 text
README Generators:
● General: https://michaeldyrynda.github.io/readme-generator/
● WP project: https://generatewp.com/plugin-readme/ or
https://tools.wedevs.com/readme/ (a little more complete)
Slide 19
Slide 19 text
No content
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
Documentation in computer science
The following are typical software documentation types:
● Request for Proposal (RFP)
● Requirements/ Statement of work/ Scope of Work (SOW)
● Software Design and Functional Specification / System Design and Functional Specifications
● Change Management, Error and Enhancement Tracking
User Acceptance Testing
The following are typical hardware and service documentation types
● network diagrams/maps
Documentation include such as feasibility report, technical documentation, operational documentation, log book, etc.
Slide 22
Slide 22 text
Documentation Audience
API : software documentation intended for programmers (API documentation)
Vs.
End users (End-user Guide)
Slide 23
Slide 23 text
Software Development
Software development process is the process of dividing software development work into
distinct phases to improve design, product management, and project management. It is also
known as a software development life cycle.
Most modern development processes can be vaguely described as agile. Other methodologies
include waterfall, prototyping, iterative and incremental development, spiral development, rapid
application development, and extreme programming.
Slide 24
Slide 24 text
Methodologies
"Traditional" methodologies such as waterfall that have distinct phases are sometimes known
as software development life cycle (SDLC) methodologies
A "life cycle" approach with distinct phases is in contrast to Agile approaches which define a
process of iteration, but where design, construction, and deployment of different pieces can
occur simultaneously.
Slide 25
Slide 25 text
Practices
Continuous integration is the practice of merging all developer working copies to a shared
mainline several times a day.
Prototyping
Software prototyping is about creating prototypes, i.e. incomplete versions of the software
program being developed. The client is involved throughout the development process, which
increases the likelihood of client acceptance of the final implementation.
Incremental development
A series of mini-Waterfalls are performed,
Rapid application development (RAD) is a software development methodology, which favors
iterative development and the rapid construction of prototypes instead of large amounts of
up-front planning.
Slide 26
Slide 26 text
Project Management Applications
Agile (Scrum) is a project management method borrowed from agile software development in
which cross-functional teams work with users/consumers to develop and release minimum
viable products frequently in short cycles.
Slide 27
Slide 27 text
Project Management Applications
In the non-tech context, work practices based on the principles in the Manifesto include the
following:
● Creating a list (or backlog) of prioritized work
● Writing tickets that describe all the units of work necessary to accomplish the items in the
backlog
● Displaying public boards so the team — and stakeholders — can track progress
● Planning out the work to be done in a sprint, or a set period of time (usually 2–4 weeks)
● Holding daily 5-10 minute standup meetings where the team checks in on progress and
discusses challenges
● Doing retrospective meetings when the sprint is over to discuss what went well, what went
wrong, and what could be improved
Scrum typically has iterations of just two weeks.
Slide 28
Slide 28 text
Other Applications
Iterative / agile design has many applications outside of software development and project
management.
Leo Babauta, the author of Zen Habits, has applied it to his writing practice:
https://zenhabits.net/agile/
Slide 29
Slide 29 text
Just Barely Good Enough
Scott Ambler states that documentation should be "just barely good enough" (JBGE), that too
much or comprehensive documentation would usually cause waste, and developers rarely trust
detailed documentation because it's usually out of sync with code, while too little documentation
may also cause problems for maintenance, communication, learning and knowledge sharing.
Slide 30
Slide 30 text
Criticism
Common agile software development pitfalls:
● Lack of overall product design
● Adding stories to an iteration in progress
● Lack of sponsor support. (Buy-in? Quick breakout side discussion - what are your tools and strategies to
encourage and support cross-departmental and institutional support/buy-in?)
● Insufficient training
● Product owner role is not properly filled
● Teams are not focused
● Excessive preparation/planning
● Problem-solving in the daily standup
● Assigning tasks
● Scrum master as a contributor
● Lack of test automation
● Allowing technical debt to build up
● Attempting to take on too much in an iteration
● Fixed time, resources, scope, and quality. (Oops - I did it again moment). Who else has to deal with director,
board, client, external constraints? Yes… the struggle is real.
● Developer burnout
Slide 31
Slide 31 text
Tools, Tips, Techniques
3.
Slide 32
Slide 32 text
NOTES
Slide 33
Slide 33 text
JOURNALING
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
No content
Slide 37
Slide 37 text
WP Plugins
Slide 38
Slide 38 text
No content
Slide 39
Slide 39 text
No content
Slide 40
Slide 40 text
No content
Slide 41
Slide 41 text
Handoffs/Signoffs
4.
Slide 42
Slide 42 text
Documentation Testing
Four key areas for testing a document include:
● Instructions
● Examples
● Messages
● Samples
Slide 43
Slide 43 text
Training and Support
Who is the recipient of your documentation?
Slide 44
Slide 44 text
Maintenance
How do you update and maintain your documentation?
Slide 45
Slide 45 text
Reference / Reflect
When do you refer back to documentation of projects?
How do you use that as a template for future projects?
Slide 46
Slide 46 text
Resources
Slide 47
Slide 47 text
Articles & Sites:
Writing Effective Documentation: [Writing Effective Documentation For WordPress End Users —
Smashing (https://wp.smashingmagazine.com/2012/07/writing-effective-wordpress-documentation/ )
Cheatsheets: [Devhints — TL;DR for developer documentation](https://devhints.io/)
Read the Docs: [Home | Read the Docs](https://readthedocs.org/) - “We host the world's documentation.
Podcasts:
Request for Commits - Changelog Media - “Ep. 5: Documentation and the Value of Non-Code
Contributions”
The Changelog - Ep. 283: Devhints - TL;DR for Developer Documentation
Hello Tech Pros - Chad Bostick - Ep 268: “The UX of Technical Documentation” - George Mocharko
JS Party - Changelog Media - Ep. 8: Good Documentation
Slide 48
Slide 48 text
Share .
Slide 49
Slide 49 text
Thank you.
@ryancanhelpyou