= 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 guide](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 documentations.
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 feedbackmproving the technical onboarding process by creating onboarding Micro Tasks for some projects.
- Identify loop-holes, problems, and challenges new and old contributors might be facing with existing documentation and help resolve themImproving documentation standards by creating a default starting template for all [genres].(https://www.mediawiki.org/wiki/Documentation/Technical_documentation_templates_and_suggestions#What_is_a_genre?).
- Help refine existing and create new- Based on feedbacks, Identify non-beginner friendly documentation standardsand help improve them.
- Improve and standardize technical onboarding processes for existing and new contributorsdocumentation review processes.
Having stated the above deliverables, here is my detailed approach to achieving them;
=== UnderstanImproving the technical onboarding the users of the documentationsprocess by creating onboarding Micro Tasks for some projects.
The consumers of documentations should be the most important factor we fathom when writing or improving technical documentations,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 projects would be created and a success criteria would be clearly defined for each task created. This would, in turn, improve their onboarding experience with certain projects.
=== Improving documentation standards by creating a default starting template for all [genres].
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. This would come in very handy for new documentarians too, as they don't have to worry too much about what the existing style guides are, they just focus on editing the templates for the genre they are currently writing for.
A 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?)
=== Based on feedbacks, Identify non-beginner friendly documentation and help improve them
The consumers of documentations should be the most important factor we fathom when writing or improving technical documentations. itIt 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, beginners inclusive, 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 havingIf you aren't sure what sort of audience you'd be having.
Some documentations are written by people who are deeply immersed in the project and hence are not beginner/new-contributor friendly. My approach to understanding the audience would include the followingSuch documentations would be identified and I would work closely with the initial documenter and other engineers to improve them.
These improvements would be based on the feedback gathered and my approach to understanding what documentations aren't beginner friendly and how to best improve a few of them would involve the following steps;
- 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(Optional).
- Iterate processes based on this research/observations.
=== Identify and Improve existing documentationsUnderstand the challenges they faced, and concepts they found difficult to understand.
- Suggest, discuss, and make changes based on feedbacks gotten.
=== Improve technical documentation review processes.
Some certain documentations still needs to be improved upon in many ways,Currently, it's a bit hard to precisely say how technical documentations are being reviewed at Wikimedia as most of it is done informally. as stated earlierThis isn't surprising, some documentations are written by people who are deeply immersed in the project and hence are not beginner/new-contributor friendly.as documentations are Wiki's which anyone can edit, Such documentation would be identified and I would work closely with the initial documenter and other engineers to improve them.however, These improvements would also be based on the feedback gathered in the `Understanding the users of the documentations` section abovthis doesn't mean a standardized review process for all documentations shouldn't be put in place.
=== Creating Micro Tasks on phabricatorStandardizing documentation review processes and properly reviewing documentations poses some advantages that would greatly the quality of technical documentation written. I aim at creating a standard documentation review process that would enforce a more organized way of getting feedbacks and improving newly created documentations.
My approach is in four basic steps to be briefly discussed below;
I was previously a Google Summ===== 1) Prototype/Self review
The writer of Code aspirant and did make a few contribua documentation is always the first reviewer of his own documentations., One of the things that brought me up to speed with making contributions to Wikimedia was the Micro tasks my mentor created (see T247835).this step involves a writer thoroughly going through his own documentation and making sure it follows Wikimedia's documentation [style guides](https://www.mediawiki.org/wiki/Documentation/Style_guide), 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[formatting](https://www.mediawiki.org/wiki/Documentation/Style_guide#Formatting_text), an attempt is being made to improve the technical onboarding process using this method (see T250830).methodologies, 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 withand use of [language](https://www.mediawiki.org/wiki/Documentation/Style_guide#Language). Micro tasks that allow new contributors get started with the project would be created and a success criteria would be defined for each task createdThis help the reviewer identify his own mistakes and makes sure the documentation conforms with the style guide. This wouldAddtionally, in turn, improve their onboarding experience with certain projectsnew documentations are to be created by strictly following this [guide](https://www.mediawiki.org/wiki/Documentation/Technical_documentation_prioritization).
=== Define standards for new and existing documentations===== 2) Peer review (Optional)
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 genreThis process involves the writer of the documentation having a colleague review the documentation for him informally, but the examples linked to are not Wikimedia's documentations and have separate style guides that might not conform with that of Wikimediathis enables the documentarian to get feedbacks from peers(who might as well be the users of the documentations) before submitting it for a proper review.
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.===== 3)
This phase would require a senior colleague to go through the documentation and check for technical accuracy and completeness of its content, This would come in very handyand how easy it would be for new documentarians too,contributors to adapt. as they don't have to worry too much about what the existing style guides are, they just focus on editing the templates for the genre they are currently writing for.Comprehensive responses would be gotten here.
===== 4) Approval
A 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?)Here, the documentation has undergone all the review processes and is published afterward.
==== Summary (TL;DR)
The above proposal aims to achieve the following;
- Understand users of the documentation and get feedbacks from them.
- Based on feedbacks, Identify non-beginner friendly documentations and help improve them.
- Create Onboarding Micro Tasks for some projects.
- Create a default starting template for all [genre's](https://www.mediawiki.org/wiki/Documentation/Technical_documentation_templates_and_suggestions#What_is_a_genre?)
= 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 - 3 (2nd - 15th 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 4 (15th - 22nd September)
- Identify projects that are poorly documented based on responses gotten from week 2 and 3.
- 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 5 - Week 7 (30th 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 documentations of the identified projects based on feedbacks gathered.
===== Week 8 - Week 9 (21st October - 3rd November)
- Identify prerequisite knowledge of documentations improved in week 5 -7
- Create Micro tasks that get users up to speed with these pre-requisites.
- Create Micro tasks that teach help users set up these projects.
===== Week 10 - 11 (11th - 17th November)
- Draw conclusions on what the current documentation standards are
- Create templates for different documentation 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