Approaching Open Source Documentation the Right Way

This talk given at the 10th anniversary of All Things Open 2022, highlights the approach I took to revamp the documentation of the Mojaloop open source project - its effectiveness and impact on the Mojaloop project.

It delineates actionable steps that other open source maintainers should adopt for their projects.

Transcript

1. The Right Way - Uduak Obong-Eren (@meekg33k) Approaching Open Source Documentation
2. Uduak Obong-Eren @meekg33k Hi, (UU-DWAK)
3. CLICK TO VIEW MORE I've traveled to more than 35 countries... IG: @meekg33k CAIRO ROME TULUM PRAGUE BUDAPEST
4. ...and I love art & architecture LA SAGRADA FAMILIA, BARCELONA LJUBLJANA, SLOVENIA FOTOGRAFISKA, SWEDEN ST STEPHEN'S BASILICA, BUDAPEST
5. https://www.edustipend.org
6. I'm a Software Engineer... Personal Health & Beauty Banking & Fintech Companies Educational Technology Travel Industries: Africa Asia Europe North America Continents: Startups Mid-size Large Multinationals Company sizes:
7. And software engineers are one of the biggest users of documentation.
8. However, if you ask software engineers what part of their job they like the least....
9. Contributed to open source as a technical writer for Mojaloop.
10. Mojaloop is an open source software that provides a model for creating interoperable payments platforms connecting digital financial providers and customers.
11. The Right Way - Uduak Obong-Eren (@meekg33k) Approaching Open Source Documentation
12. The Right Way Open Source Documentation
13. The Right Way Open Source Documentation
14. The Right Way Open Source Documentation
15. The Right Way Open Source Documentation Open source software is software with source code that anyone can inspect, modify, and enhance. Source: https:www.opensource.com
16. The Right Way Open Source Documentation Documentation is the body of information that describes the workings of a (software) product to the people who develop, deploy, enhance and use it. Source: https:www.techtarget.com
17. Categories of Documentation Internal vs External Technical vs Non-Technical Product vs Process
18. Categories of Documentation Internal documentation refers to documentation where the users are internal to an organization whereas external documentation is for external users. Internal vs External Technical vs Non-Technical Product vs Process
19. Categories of Documentation Internal documentation refers to documentation where the users are internal to an organization whereas external documentation is for external users. Internal vs External Technical vs Non-Technical While product documentation embodies information about a product, e.g. technical requirements, user manuals; process documentation outlines the steps involved in building the product. Product vs Process
20. Categories of Documentation Internal vs External Technical vs Non-Technical Technical documentation is typically for technical users. e.g. developers while non-technical documentation, e.g. user manuals is for non-technical users. Product vs Process While product documentation embodies information about a product, e.g. technical requirements, user manuals; process documentation outlines the steps involved in building the product. Internal documentation refers to documentation where the users are internal to an organization whereas external documentation is for external users.
21. The Right Way Open Source Documentation What does that even mean?
22. The Right Way Open Source Documentation What does that even mean? Who determines what way is right
26. What car is right ?
30. Which is the right costume?
31. Or is having no costume the right costume?
33. Which documentation is the right way?
34. But before we go further, a quick question...
35. Raise your hand if you've ever read poor documentation...
36. Raise your hand if you've chosen to go with one technology/framework over another only because of the documentation...
37. Mojaloop provides APIs for financial interoperability by connecting digital financial providers and customers. Technical Specification API Reference Documents Architecture Documents
43. How we approached open source documentation the right way at Mojaloop
44. Vision: Documentation as a Product @meekg33k
45. Documentation to be the tool to drive the adoption of Mojaloop technology.
46. 1. Create User-centered Documentation.
47. User-centered Documentation Who are our users? What are their needs? What are they trying to accomplish? How can we surface information to help them accomplish what they want to?
48. User-centered Documentation Who are our users? What are their needs? What are they trying to accomplish? How can we surface information to help them accomplish what they want to?
49. Mojaloop User Personas Regulators Mostly government agencies looking for a regulated system to help drive financial inclusion Developers Tasked with the technical tasks of integrating the technology Participants Payment Service Providers, Banks and Non-Banks, Aggregators etc. Hub Operators They are the builders that maintain interoperability. e.g. National Switches m Funders/Investors Impact Investors, financial institutions Contributor Looking to make an open source contribution
50. 2. Develop an Information Architecture. @meekg33k
51. Information Architecture Information architecture focuses on organizing, structuring, and labeling content or information in an effective and sustainable way.
52. Information Architecture Information architecture focuses on organizing, structuring, and labeling content or information in an effective and sustainable way. Information architecture is the discipline of making information findable and understandable
53. Information Architecture Who are our users? What are their needs? What are they trying to accomplish? How can we surface information to help them accomplish what they want to?
55. 3. Define metrics for measurement. @meekg33k
56. How do we measure that we are moving towards our desired goal for our new documentation? Measurement
57. Ease of discovery Information relevance How do we measure that we are moving towards our desired goal for our new documentation? Ease of navigation Measurement - Defining Metrics d n r
58. User Needs Ease of finding relevant guides and information to start contributing. Relevance of information presented in Getting Started section. Time to first pull request as a result of information from documentation. Needs relevant guide and information to allow them contribute. User-Specific Metrics: Contributor
59. Now it's time to implement...
63. Features & Implementation Clean user interfaces with clear CTA. Replacement of text and images for demos with videos.
64. Features & Implementation Clean user interfaces with clear CTA. Use of mobile responsive assets. Replacement of text and images for demos with videos. Addition of sandboxes for testing APIs.
65. Features & Implementation Clean user interfaces with clear CTA. Use of mobile responsive assets. Replacement of text and images for demos with videos. Addition of sandboxes for testing APIs. Multi-OS (inclusive) documentation. Feedback mechanism.
66. Clear CTA
67. Top-level navigation
68. 4. Automate documentation lifecycle. @meekg33k
70. Design Implementation Documentation Lifecycle Review Deploy
71. Design Implementation Documentation Lifecycle Review Deploy Feedback
72. Documentation Lifecycle Management Manage the documentation lifecycle as an agile process. Build feedback into the documentation lifecycle.
73. Documentation Lifecycle Management Manage the documentation lifecycle as an agile process. Automate release and deployment of documentation. Build feedback into the documentation lifecycle. Use tools that allow for easy versioning as part of release.
74. Support for versioning
75. 5. Empower the community to contribute. @meekg33k
76. Community Management Contributing Guides Documentation Style Guide Documentation Review Process Community Standards FAQs and Help Resources
78. The Right Way Open Source Documentation 01 User-Centered Documentation
79. The Right Way 02 Open Source Documentation 01 User-Centered Documentation Information Architecture
80. The Right Way 02 03 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Information Architecture
81. The Right Way 02 03 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Information Architecture Product
82. The Right Way 02 03 04 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Documentation Lifecycle Management Information Architecture Product
83. The Right Way 02 03 04 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Documentation Lifecycle Management Information Architecture Product Process
84. The Right Way Community Management 02 03 04 05 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Documentation Lifecycle Management Information Architecture Product Process
85. The Right Way Community Management 02 03 04 05 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Documentation Lifecycle Management Information Architecture Product Process People
86. The Right Way Community Management 02 03 04 05 Open Source Documentation 01 Measurement & Feedback User-Centered Documentation Documentation Lifecycle Management Information Architecture Product Process People
87. Thank You Happy to take questions @meekg33k