= Profile Information
**Name**: Bello Gbadebo
**Email**: gbahdeybohbello@gmail.com
**IRC nick**: Gbahdeyboh
**Location**: Lagos, Nigeria
**Typical working hours**: Between 6pm and 2am WAT(UTC+01:00)
I was introduced to open source a few years ago, which was around the same time my journey in tech began. I've ever since then been interested in contributing and giving back to the community via open source contributions. It can be a bit overwhelming at times, considering the fact that you need quite some strong technical knowledge to make code contributions to certain open source projects. But writing code isn't the only way to give back to the community or contribute to open source, I figured this out early enough and started contributing my little quota to open source by building and fostering the growth of communities around open source.
When this year's GSoD was announced, I figured out one aspect of making contributions to open source I haven't really explored asides building communities and writing code is writing technical documentations. Although I've written several technical articles and a few documentations for some projects I've previously worked on which aren't open source, I strongly feel participating in programs like GSoD would not only let me improve my technical writing skills, but also give me an opportunity to explore new ways of contributing to open source while learning at the same time.
= Synopsis
Wikimedia documentations serve as one of the first contact of new contributors to Wikimedia projects, in fact, even after getting familiar with the codebase, engineers working on this project still have to revisit the documentation at regular intervals. Therefore, the importance of a reliable, rich, well-structured, and uniform documentation across all projects can never be overemphasized.
Over the years, Wikimedia engineers have made several successful attempts to improve the existing documentation in many ways.
Here's a snippet from T203131:
> There are a plethora of open tickets requesting new and improved Technical documentation for Toolforge. Improvements to documentation have also been consistently requested in the annual Toolforge survey. Gaps in consistency and documentation have been identified by users and collaborators. Many aspects of Toolforge are well-documented and some are not documented at all. This can lead to an inconsistent experience for technical collaborators.
The above lays emphasis on the inconsistent nature of documentations, one of such reasons is due to some aspects of Toolforge being documented and some not being documented at all.
Wikimedia has a rich [documentation](https://www.mediawiki.org/wiki/Documentation) guide which might be unavoidably overwhelming for new contributors, I've observed a few loop-holes that might cause inconsistencies across new documentations documentarians write.
- The [documentation](https://www.mediawiki.org/wiki/Documentation) gives [technical documentation templates](https://www.mediawiki.org/wiki/Documentation/Technical_documentation_templates_and_suggestions) which is structured based on genres. These genres provide examples that mostly link to external documentation resources such as [Google](https://cloud.google.com/sdk/docs/), [heroku](https://devcenter.heroku.com/categories/platform-api), [github](https://guides.github.com/activities/hello-world/), etc. All the external resources linked to have different standards for writing technical documentations some of which do not align with that of Wikimedia. This might confuse documentarians to use the styles in the external resource linked or perhaps mix its styles with that of Wikimedia which can lead to Inconsistency in documentation formats.
- The existing documentation for technical writers might be a bit overwhelming to new documentarians because it contains a lot of links to other resources. I had to constantly open new tabs for several links found in every documentation page I visited.
- According to a chat I had with a Wikimedia engineers, he said; `Some of the docs are written by people who are immersed in the project hence, they can be non-beginner friendly in many cases because the person who wrote the docs are the ones who built the tool`. While engineers who built a tool writing a technical documentation for their tool isn't a problem, It could become a problem if they always assume contributors would have the same degree of expertise they do. To further buttress this point, [here](https://wikimedia.zulipchat.com/#narrow/stream/100747-general/topic/Improve.20new-contributor.20onboarding/near/196995959) is what a GSoC student said about the current [gerrit documentation](https://www.mediawiki.org/wiki/Gerrit/Tutorial). `For example the current guide to Gerrit: https://www.mediawiki.org/wiki/Gerrit/Tutorial will take a first-time committer atleast 30-45 minutes even if they want to do very simple patches, however a GitHub repository would take 5-10 minutes at most: forking takes a few seconds, a few minutes to commit and another few to submit a pull request`. The thread can be read to the end to see other problems some of these documentations have in which some successful attempts were clearly made to fix the problems stated.
- One other problem that causes inconsistencies is that it is really difficult to keep track of some of Wikimedia's projects, the [New Developers](https://www.mediawiki.org/wiki/New_Developers) guide clearly states that `The maintainers of each software project are pretty free to choose the infrastructure they prefer. In general, basically all software projects have......`. While this allows the maintainers of projects to use tools they are most comfortable using, it makes it difficult to track projects which can lead to inconsistencies in documentation. This [discussion thread](https://wikimedia.zulipchat.com/#narrow/stream/220258-gsoc20-outreachy20/topic/WikiContrib/near/196968331) downwards clearly shows the sort of problems this poses as maintainers have some of Wikimedia's projects on their personal accounts.
= Project Outline
Having highlighted very few observations above, it becomes really evident that a lot could still be done to improve the experience that new and old contributors have with existing and newly created documentation.
A standardized style of documentation across all of Wikimedia's projects would create uniformity and make new contributors familiar with the structure of new documentations they visit.
= Deliverables
- Identify more causes of inconsistencies across documentation and ways in which they can be improved by iterating upon user feedback.
- Identify loop-holes, problems, and challenges new and old contributors might be facing with existing documentation and help resolve them.
- Help refine existing and create new documentation standards.
- Improve and standardize technical onboarding processes for existing and new contributors.
- Improve technical documentation review processes.
- Identify the different platforms Wikimedia's projects exist on(i.e Github, Gitlab, etc) and make sure the documentations follows the defined standard.
Having stated the above deliverables, here is my detailed approach to achieving them;
=== Understanding the users of the documentations
The consumers of documentations should be the most important factor we fathom when writing or improving technical documentations, it is of utmost importance to understand one's audience and experience level, in fact, it is best to write documentations that take into consideration all experience levels if you aren't sure what sort of audience you'd be having. My approach to understanding the audience would include the following;
- Have discussions with already existing users of the documentation.
- Onboard new contributors and observe/record their experience with the existing documentation.
- Understand the challenges they faced, get their suggestions on how they think it could be improved.
- Iterate processes based on this research/observations.
=== Define standards for new and existing documentations
Having uniformity across all documentations gives the audience a familiar feel on every Wikimedia documentation, which is important. The current [guidelines](https://www.mediawiki.org/wiki/Documentation) for documenters are rich in information and is a good place to start. But a few improvements can still be made. The [writing process](https://www.mediawiki.org/wiki/Documentation/Technical_writer_guide) and [genre table](https://www.mediawiki.org/wiki/Documentation/Technical_documentation_templates_and_suggestions#What_is_a_genre?) define what is expected of each documentation based on its genre, but the examples linked to are not Wikimedia's documentations and have separate style guides that might not conform with that of Wikimedia.
I plan to create a default template for each type of documentation genre that can be used by documentarians to get started. A very good example of such a template example can be found [here](https://www.digitalocean.com/community/markdown). With such a template provided for each documentation genre, documentarians don't have to remember all the style guidelines/structure or reference it always, they just pick a template that has all guidelines followed already and edit it to suit the documentation content.
=== Identify and Improve existing documentations
Some certain documentations still needs to be improved upon in many ways, I have 3 basic approaches to improving existing documentations.
===== 1. Improving the written content
As stated earlierThis would come in very handy for new documentarians too, some documentations are written by people who are deeply immersed in the project and hence are not beginner/new-contributor friendly.as they don't have to worry too much about what the existing style guides are, Such documentation would be identified and I would work closely withthey just focus on editing the templates for the initial documenter and other engineers to improve themgenre they are currently writing for.
===== 2. Adding visuals where necessaryA list of all genre's that templates would be created for can be found [here](https://www.mediawiki.org/wiki/Documentation/Technical_documentation_templates_and_suggestions#What_is_a_genre?)
Visual illustrations, Images, screenshots, etc can help communicate information more effectively and accurately alongside a well-explained text. There is currently a guide for what kind of [graphics](https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Graphics_in_technical_documentation) can be used in Wikimedia's documentations. The presence of this guide indicates the importance of visuals in documentations.
I created a simple flow-chart that depicts the current workflow of Gerrit and sheds more light on the [what is gerrit](https://www.mediawiki.org/wiki/Gerrit/Tutorial#What_is_Gerrit?) section in its documentation.that
{F31866771}=== Identify and Improve existing documentations
It can be immediately observed that the flow-chart adds more meaning and context to the explanation given in that section,Some certain documentations still needs to be improved upon in many ways, as stated earlier, some documentations are written by people who are deeply immersed in the project and hence are not beginner/new-contributor friendly. Such documentation would be identified and I would work closely with the initial documenter and other engineers to improve them. creating such visuals is one of the ways I plan on adding more value to documentationsThese improvements would also be based on the feedback gathered in the `Understanding the users of the documentations` section above.
===== 3. Adding videos, recording explaining certain terms, concepts, and workflows in documentations
One of my favourite documentation on Wikimedia is the documentation of [phabricator](https://www.mediawiki.org/wiki/Phabricator/Help). The reason is simple.. Videos!! I'll rather watch a video explaining concepts than reading long texts! I prefer videos and a lot of other people do too, giving the audience a chance to choose how they want to consume our resources can greatly impact how they interact with documentations. It shows we care about their preference and can be more welcoming to new contributors.
A very good example of documentations where video tutorials might come in handy is that of [Gerrit](https://www.mediawiki.org/wiki/Gerrit/Tutorial), Mediawiki setup, and many more.
=== Creating Micro Tasks on phabricator
I was previously a Google Summer of Code aspirant and did make a few contributions. One of the things that brought me up to speed with making contributions to Wikimedia was the Micro tasks my mentor created (see T247835). They were indeed very helpful and created a clear path to what needs to be learned as a prerequisite to contributing to the code base. Currently, an attempt is being made to improve the technical onboarding process using this method (see T250830). This is a really good way to get new contributors to get their hands dirty quickly and get up to speed with contribution requirements for specific projects. I am going to be taking this same approach for certain projects that might be a bit difficult to get started with. Micro tasks that allow new contributors get started with the project would be created and a success criteria would be defined for each task created.
= Tentative Timeline
Community bonding period (7th - 25th August)
===== Week 1 (26th August - 1st September)
- Analyze the project in detail with my mentors.
- Discuss about:
* How often the tasks should be reviewed.
* Share schedules and decide on a weekly/daily workflow.
* Tools and resources that can be used.
* Bi-weekly and daily project reports.
===== Week 2 (2nd - 8th September)
- Investigate causes of inconsistencies in existing documentations
* Interact with documenters and engineers.
* Create a survey gathering user feedback on documentation.
* Collate results gathered from these surveys.
* Study responses and derive insights from them.
* Draw conclusions from derived insights.
===== Week 3 (9th - 15th September)
- Identify projects that are poorly documented based on responses gotten from week 2.
- Identify projects that have documentation that does not conform with Wikimedia's style guide.
- Collate the identified projects.
- Identify loopholes in these projects and work closely with engineers and contributors on what the best way to fix them is
===== Week 4 - Week 6 (16th September - 13th October)
- Decide on which documentation to be improved depending on how they conform with my skillset.
- Study and understand the projects.
- Improve some existing documentation of several projects based on feedback gathered.
- Create Micro tasks that get users started easily with such projects.
===== Week 7 - Week 8 (14th- 27th October)
- Determine which documentation lacks visuals and graphics.
- Curate a list of such documentations.
- Create required visuals/graphics for such documentations to better illustrate explanations.
===== Week 9 - Week 10 (28th October - 10th November)
- Determine which documentation lacks video tutorial walkthroughs.
- Curate a list of such documentations.
- Create video tutorials for some certain documentations.
===== Week 11 (11th - 17th November)
- Draw conclusions on what the current documentation standards are
- Help define the documentation standards more appropriately
- Create templates for different documentations genre's that can help documentarians get started easily.
- Debate methods that can help standardize these guides across all projects.
===== Week 12 (18th - 24th November)
- Work on pending/outstanding tasks.
- Reviewing all documentations and processes that were improved.
===== Week 13 (25th - 29th November)
- Writing a final report.
- Submitting the final report for review and evaluation.
== Past Contributions
While I'm yet to complete documentation centric tasks, I've made some attempts to making code contributions to Mediawiki.
These contributions were not merged, but sharing them sure does depicts that I'm familiar with the technicalities of some of Wikipedia's projects.
- [589804](https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/589804/)
- [587578](https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/587578/)
- [589737](https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/589737/)
== Mentors
- Sarah R. Rodlund
- @apaskulin