Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Oops!.. I Did It Again. How Documentation And Journaling Can Save You And Your Team From Making The Same Mistakes.

Oops!.. I Did It Again. How Documentation And Journaling Can Save You And Your Team From Making The Same Mistakes.

Join me on my journey from random note-taking and scattered doodles to an organized system of documentation. I have been on a personal quest to establish a healthy, productive habit of ritual documentation and journaling. Both for workplace projects and personal growth, I have been experimenting with and assessing different practices of recordkeeping and review with the end goal of reflection, archiving, and establishing workflows and protocols.

Drawing from concepts of software development, time management, and agile flows, I will lead you through what I have discovered and will share various tools and systems that have been beneficial along the way. Part demo, part open forum, this workshop will help you achieve your path to documentation Nirvana.

Ryan King

April 18, 2018
Tweet

More Decks by Ryan King

Other Decks in Technology

Transcript

  1. @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

    View full-size slide

  2. Good Mornin' !

    View full-size slide

  3. Overview
    1. Minding your Mornings
    2. Working Workflows
    3. Tools, Tips, Techniques
    4. Handoffs/Signoffs

    View full-size slide

  4. Introductions

    View full-size slide

  5. Minding your Mornings
    1.

    View full-size slide

  6. 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.

    View full-size slide

  7. 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

    View full-size slide

  8. 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.

    View full-size slide

  9. 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.

    View full-size slide

  10. 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

    View full-size slide

  11. 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?"

    View full-size slide

  12. Working Workflows
    2.

    View full-size slide

  13. 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

    View full-size slide

  14. 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)

    View full-size slide

  15. 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.

    View full-size slide

  16. Documentation Audience
    API : software documentation intended for programmers (API documentation)
    Vs.
    End users (End-user Guide)

    View full-size slide

  17. 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.

    View full-size slide

  18. 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.

    View full-size slide

  19. 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.

    View full-size slide

  20. 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.

    View full-size slide

  21. 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.

    View full-size slide

  22. 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/

    View full-size slide

  23. 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.

    View full-size slide

  24. 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

    View full-size slide

  25. Tools, Tips, Techniques
    3.

    View full-size slide

  26. Handoffs/Signoffs
    4.

    View full-size slide

  27. Documentation Testing
    Four key areas for testing a document include:
    ● Instructions
    ● Examples
    ● Messages
    ● Samples

    View full-size slide

  28. Training and Support
    Who is the recipient of your documentation?

    View full-size slide

  29. Maintenance
    How do you update and maintain your documentation?

    View full-size slide

  30. Reference / Reflect
    When do you refer back to documentation of projects?
    How do you use that as a template for future projects?

    View full-size slide

  31. 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

    View full-size slide

  32. Thank you.
    @ryancanhelpyou

    View full-size slide