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

Oops!.. I Did It Again. How Documentation And J...

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
  2. 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.
  3. 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
  4. 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.
  5. 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.
  6. 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
  7. 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?"
  8. 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
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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.
  14. 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.
  15. 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/
  16. 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.
  17. 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
  18. Documentation Testing Four key areas for testing a document include:

    • Instructions • Examples • Messages • Samples
  19. Reference / Reflect When do you refer back to documentation

    of projects? How do you use that as a template for future projects?
  20. 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