Continuous Documentation The best time is now Kenigbolo Meya Stephen, Frontend Engineering Lead at BCaster

1. Continuous Documentation
The best time is now
1@expensivestevie

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

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

5. https://www.youtube.com/watch?v=XtS_t3F
HWe0
https://bit.ly/30Pg7W0
5

6. 1.
WHAT IS CONTINUOUS DOCUMENTATION
6
66@expensivestevie

7. CONTINUOUS DOCUMENTATION
Continuous documentation is a documentation pattern
we’ve developed within the BCaster Frontend team where
the primary focus of taking into consideration constant
changes/improvements in code and business logic to be
reflected internally/externally for every single closed sprint.
7
77@expensivestevie

8. “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.
8
88@expensivestevie

9. “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?
9
99@expensivestevie

10. THE PROBLEM COMES WITH
ANOTHER
CHANGE
CHANGE
EVEN MORE
CHANGES
10
1010@expensivestevie

11. 2.
WHY IT IS IMPORTANT
11
1111@expensivestevie

12. “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
12
1212@expensivestevie

13. 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?
13
1313@expensivestevie

14. 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
14
1414@expensivestevie

15. 1515@expensivestevie

16. 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
16
1616@expensivestevie

17. 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.
17
1717@expensivestevie

18. 1818@expensivestevie

19. Unhelpful phrasing
✘ “Simply run the tests”..
✘ “Just write a compiler then it simply works”.
✘ “Simply”, “Just”, “Simple”, “Actually”, “Easy”, “Easily”, “Obviously”.
19
1919@expensivestevie

20. 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.
20
2020@expensivestevie

21. 4.
HOW TO IMPROVE VIA CONTINUOUS
DOCUMENTATION
Preconceptions are pure evil
21
��
2121@expensivestevie

22. “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
22
2222@expensivestevie

23. Our process is easy
MAKE CHANGES
DOCUMENT
CHANGES
SCREEN
UPDATED DOCS
23
2323@expensivestevie

24. 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.
24
2424@expensivestevie

25. 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
25
2525@expensivestevie

26. 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?
26
2626@expensivestevie

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

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

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

30. 5.
MOVING FORWARD
Continuous Documentation is all about continuous improvement to
documentation practices.
30

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

32. DocLint target platforms
JavaScript
(JS Package)
RUST
(CLI)
BROWSERS
(EXTENSION)
32

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

34. 34
That’s all for today folks
34@expensivestevie

35. 35
Thank You! Kiitos! (Key-Toss!)
Any questions?
You can find me at
▰ Twitter @expensivestevie
▰ Github @kenigbolo
35@expensivestevie