Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Continuous Documentation: The Best Time is Now

544 views

Published on

Bad or non existent documentations are almost always the ripple effect of not writing documentation when it matters. In this talk I’ll take a quick deep dive into the importance of “Continuous Documentation” and how this is important for creating an amazing developer experience.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Continuous Documentation: The Best Time is Now

  1. 1. Continuous Documentation The best time is now 1@expensivestevie
  2. 2. Hello! Terve! I’m Kenigbolo Meya Stephen Front-End Engineering Lead @bcaster Arch Conveyer/Community Manager @TheCodeAfrique You can find me on twitter at @expensivestevie 22@expensivestevie
  3. 3. WHAT I’LL BE TALKING ABOUT 4 😉 ✘ What is Continuous Documentation. ✘ Why is it important. ✘ Common pitfalls in current documentation practices. ✘ How to improve by implementing Continuous Documentation ✘ Continuous Documentation - Moving forward 👉 44@expensivestevie
  4. 4. 1. WHAT IS CONTINUOUS DOCUMENTATION 5 55@expensivestevie
  5. 5. CONTINUOUS DOCUMENTATION Continuous documentation is a documentation pattern we developed at BCaster that takes into consideration constant changes/improvements in code and business logic to be reflected internally for every single closed sprint. 6 66@expensivestevie
  6. 6. “In our industry, change occurs so fast that it sometimes is difficult to catch all of it. This is the same case for the documentation and unfortunately release notes alone do not cut it. 7 77@expensivestevie
  7. 7. “The open source (OSS) world uses Requests For Comments (RFC) however even in that world the RFC’s are rarely summarized. What do you use internally in your company? 8 88@expensivestevie
  8. 8. THE PROBLEM COMES WITH ANOTHER CHANGE CHANGE EVEN MORE CHANGES 9 99@expensivestevie
  9. 9. 2. WHY IT IS IMPORTANT 10 1010@expensivestevie
  10. 10. “The reasoning behind a change that you fail to document today might become lost forever resulting in knowledge base gap. What you end up having is an unsynchronized knowledge base 11 1111@expensivestevie
  11. 11. TYPICAL DOCUMENTATION TYPES ✘ Proprietary software - Docs included and maintained ✘ Popular Frameworks - Dedicated teams for docs. ✘ Your company - Developers make docs? Dedicated documentation team? How do you handle your documentation? 12 1212@expensivestevie
  12. 12. 3. COMMON PITFALLS IN CURRENT DOCUMENTATION PRACTICES If you just said to yourself “we’re definitely doing it right” then trust me when I say you’re definitely doing it wrong 13 1313@expensivestevie
  13. 13. 1414@expensivestevie
  14. 14. SIMPLE THINGS YOU’RE PROBABLY DOING WRONG Readme’s If majority of your code documentation are mostly README.md documents then you’ve been doing a lot of dis-service to what documentation should be Unhelpful Phrasing Do you have a word checker for your documentation? Do you spot unhelpful phrases in documentation? Can you define what an unhelpful phrase is? If the answer to any of those questions is “No” then there’s room for improvement Inconsiderate Writing Can you take your documentation and give to a non technical person and expect them to make any sense out of it? If you answered that question with “but it’s a technical doc” then there’s definitely room for improvement 15 1515@expensivestevie
  15. 15. README ✘ Readme’s are supposed to be an entry point to your documentation as opposed to it being your main documentation ✘ If you’re having more than three sections in a Readme that already signifies there is a lot of information that needs to be somewhere else. ✘ Ever heard about clutter? Extensive readme’s are simply that - Clutter. 16 1616@expensivestevie
  16. 16. 1717@expensivestevie
  17. 17. Unhelpful phrasing ✘ “Simply run the tests”.. ✘ “Just write a compiler then it simply works”. ✘ “Simply”, “Just”, “Simple”, “Actually”, “Easy”, “Easily”, “Obviously”. 18 1818@expensivestevie
  18. 18. INCONSIDERATE WRITING ✘ Gender favouring - “Hey Guys”, “he”, “his”, “dude” etc. ✘ Avoid race related phrases (tricky one but we’ll see how to deal with this later on). ✘ Polarizing/Unequal Phrasing - “It has always been like that” - It’s safe to say we all have that one guy in our company. 19 1919@expensivestevie
  19. 19. 4. HOW TO IMPROVE VIA CONTINUOUS DOCUMENTATION Preconceptions are pure evil 20 �� 2020@expensivestevie
  20. 20. “Always remember that documentation is a form of communication. Communication is a two way street. If your documentation is ambiguous then you have failed to communicate 21 2121@expensivestevie
  21. 21. Our process is easy MAKE CHANGES DOCUMENT CHANGES SCREEN UPDATED DOCS 22 2222@expensivestevie
  22. 22. README ✘ First ensure your document is in Markdown format ✘ Badges are good and informative so if you have CI badges put them up there. ✘ Create a separate folder for docs in every repository. Markdown documents can be used to link to other markdown documents.. ✘ Your readme should contain simply the description and getting started installation instructions. Every other detail should be a link to a respective Markdown document. 23 2323@expensivestevie
  23. 23. UNHELPFUL PHRASING ✘ Documentations are a tools for communication as opposed for a place to expand your ego. Do not assume that everyone using them is on the same skill level as you. ✘ Call a non-technical person or content writer to help you review. Like pair programming, a second pair of eyes is always good. ✘ Review documentation changes just as you rigorously review your code. It is equally as important 24 2424@expensivestevie
  24. 24. INCONSIDERATE WRITING Don’t you think Primary/Replica sounds better than Master/Slave? How about we use AllowList/DenyList instead of Whitelist/Blacklist? Doesn’t “Hey everyone” sound more gender neutral than “Hey guys”? I’m guessing now you’re already thinking about a lot of phrases that you use but never considered inconsiderate up until this point? 25 2525@expensivestevie
  25. 25. “Release notes are nice and should be a must have for every major change irrespective of the size of your company and regardless of if you use semantic versioning or not. 26
  26. 26. “There is no such thing like too much of good documentation. If there’s a reasonable change somewhere there should be a corresponding documentation update to show that change. 27
  27. 27. “Auto generating documentation from code while being a good thing can most times result in a lot of common mistakes flying below the radar. Treat your documentation quality better than you even treat code quality. 28
  28. 28. 5. MOVING FORWARD Continuous Documentation is all about continuous improvement to documentation practices. 29
  29. 29. “Currently working on a documentation spec that enforces certain standards but are flexible enough to be configurable. Also currently working on a linting tool using those standards and it will be called DocLint. It will be to documentation as EsLint is to Javascript 30
  30. 30. DocLint target platforms JavaScript (JS Package) RUST (CLI) BROWSERS (EXTENSION) 31
  31. 31. “Interested in helping out? Let’s have a chat and brainstorm ideas on how to proceed with this. We’ve created an internal TC at BCaster for this very purpose and I’d be more than glad to share more info on this. 32
  32. 32. 33 That’s all for today folks 33@expensivestevie
  33. 33. 34 Thank You! Kiitos! (Key-Toss!) Any questions? You can find me at ▰ Twitter @expensivestevie ▰ Github @kenigbolo 34@expensivestevie

×