Agile presentation
- 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?
- 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.
- 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
- 42. This presentation: bit.ly/2oMDP6u Github: https://github.com/CodeForAfrica Twitter: twitter.com/Code4Africa Medium: https://medium.com/@CodeForAfrica
- 43. Q/A