Why documentation in agile development processes suck and how to fix it.

1. Why documentation in
agile processes sucks...
and how to fix it
Brenda Nyokabi

2. Introduction

3. Brenda Nyokabi
Technologist
Code for Africa
Github
Twitter

4. Pan-African
Federation
Code for Africa is a
federation of indigenous
civic tech + civic media
labs in 9 countries, in
Ghana, Kenya, Morocco,
Nigeria, Sierra Leone,
Senegal, South Africa,
Tanzania, and Uganda,
operating alongside a
sister network of
independent
investigative
newsrooms in 22
countries.

5. Global
Networks
Code for Africa is
underwritten by a
network of global
partners who offer deep
industry know-how,
cutting-edge technology
and substantive
resources.
CfA is an initiative of the
International Center for
Journalists (ICFJ) in the
U.S.

6. What is Agile development?
Agile software development refers to software development
methodologies centered around the idea of iterative
development, where requirements and solutions evolve
through collaboration between self-organizing cross-
functional teams.

7. Agile manifesto
We are uncovering better ways of developing software by doing it and
helping others do it. Through this work we have come to value:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on the right, we value the items on
the left more.

8. Documentation
Working software over comprehensive documentation
“The main goal of effective documentation is to ensure that
developers and stakeholders are headed in the same
direction to accomplish the objectives of the project.”

9. TYPES OF DOCUMENTATION
Process Documentation
Standards, project plans, reports, schedules
Product Documentation
Requirements, business logic, tech specification

10. Our focus is on system documentation
GENERAL STRUCTURE OF AGILE DOCUMENTATION

11. DEVELOPER’S
PERSPECTIVE
Why do developers find it hard to document code?

12. 1. Frequent source
code
change/require
ment changes
Frequently changes
in requirements
and specification
leads to poor
documentation or
none at all
Why document when we the
requirements will change in the
next sprint

13. 2. Pressure to
deliver the
project on time
The developer needs to
deliver the project on
time. The company wants
to deliver the project as
soon as possible because
of the client’s
requirements, and the
first thing that goes down
the drain is
documentation
No time to document , ship ASAP!

14. 3. Developers
are too close to
the projects
Developers are in a
position where
they understand
whats going on in a
codebase and take
for granted the
need to explain
things as clearly as
possible.
Google is your friend

15. 4. Developers don't
need documentation
Developers understand
what they are working
choose to skip
documentation which
sounds reasonable, until
you came back to your
codebase and have no
idea what problem your
code was solving
What do you mean by documentation,
UML diagrams?

16. Value of documentation in
Agile
Why document?

17. “Agile methods are not opposed to documentation, only to valueless
documentation. Documents that assist the team itself can have value,
but only if they are kept up to date.
Michael Nygard

18. Documentation verifies the
accuracy of our assumptions about
what we deem common
understanding, making it easier for
everyone to be on the same page.
Are we on the same page ?
1. Common
understanding

19. It’s not uncommon for developers
to complain about their product
managers, saying they “don’t
really understand how the
software actually works”.
Documentation can help
developers bridge that gap and
fosters Empathy Driven
development(EDD) by providing
context
2. Create empathy
Could you explain this to
me again ?

20. Documenting current and
past decisions helps with
future problem solving
3. Aid future self/team in
making better decisions
Why did we choose
technology x over y again ?
What problem were we solving?

21. Documenting team
processes helps junior hires
get started quicker on your
team. This can apply to any
category of documentation
like wiki’s , readmes or
any other automated tasks.
Example
4. Helps with onboarding
processes
How do you
set up this repo and other xn
questions

22. Every once in a while we end up
with problems that are not as
trivial as expected. For cases like
this, creating documentation
makes it easier to unpack the
problem analytically.
4. Creative problem
solving:
Why does the svg file not
inherit max height of container?

23. DOCUMENTATION METRICS

24. What makes for a good doc?
Can you measure good documentation? What I search for
when making design and software architecture decisions:

25. 1. Easy to navigate
React.js

26. 2. Offers sequential steps to reach specific goal.
Jekyll && Postgresql

27. 3. Offers occasional visual aid, in form of diagram
MATERIAL UI

28. 4. Embeds introductory learning 'back tracks' throughout docs
Redux.JS

29. 5. Provides links that provide more useful insight
VICTORY.JS

30. MAKING DOCUMENTATION
WORK FOR AGILE TEAMS

31. SOURCE CODE DOCUMENTATION
1. Write good comments or none at all.
1. Define naming conventions and project structure. Include nice
to have tools for standardizing the your code base, using eslint
tools, maybe typescript if it works for your team.
2. Introducing tracking and documenting tools such as
READMEs, PR and ISSUE TEMPLATES, wikis for your projects.
1. Keep it simple and concise. DRY (Don’t Repeat Yourself)
principle.

32. Issue Template
Template

33. PR templates
Template

34. Tip for better documentation

35. 1. Executable
specification:
Use the Just-In-Time (JIT)
approach to write the detailed
specifications which is a single
source information that is the
test to outline the
requirements/design and
validate your work.
DEMO:
Hurumap-ui/Storybook

36. 2. Document late
Write system overviews
towards end of the
development of a
release. This way you
document what you
have actually built
DEMO:
CFA WIKI

37. 3. Avoid
overlapping
documentation
This requires
building larger
documents from
smaller ones. You
can create Wikis
sort of
documentation to
create different
single pages for
single topics.
DEMO:
CFA WIKI

38. 4. Simplify
documentation:
Write a 5-page
document, rather
than a a document
with 50 pages,
with bullet points
to provide context.
DEMO:
READ ME

39. 5. Purpose oriented
goal
Create a document to
cater to some
immediate goal of your
project.
In the case of
documentation, one size
never fits all.
Each system has its own
unique documentation
needs that also mean
you cannot reuse the
repeatable process to
create documents.
BARE MINIMUM
CONCEPT NOTE
Builds on the work plan and the
reporting document
WORK PLAN
REPORTING DOCUMENT

40. Helpful tips for organizational teams
1. The documentation effort must be baked into the agile process
Wiki thursdays , ISSUE AND PR TEMPLATES
1. Everyone contributes to the documentation effort, for each
sprint
2. There should be a "point person" who manages the
documentation effort
3. The tech writers need to be engineers
4. No person is a silo => Write to be understood especially when
writing user facing documentation

41. Resources
https://www.atlassian.com/software/confluen
ce/templates
https://software-documentation-
template.readthedocs.io/en/latest/readme.ht
ml
https://keepachangelog.com/en/1.0.0/
https://opensource.guide/best-
practices/#documenting-your-processes

42. This presentation: bit.ly/2oMDP6u
Github: https://github.com/CodeForAfrica
Twitter: twitter.com/Code4Africa
Medium: https://medium.com/@CodeForAfrica

43. Q/A