My name is Joseph Mawa. I am a technical writer and web developer. Below is my proposal for the project Create easy to learn tutorials for beginner users of Wechaty under Google Season of Docs 2021.
Statement of interest
- Personal information
- Name: Mukosa Joseph Mawa
- Email: mjm.mawa@gmail.com
Professional information
Summary
I am a self-taught web developer and technical writer with a passion for open source software. I have published a number of beginner friendly technical articles on dev.to and freeCodeCamp. Before transitioning into tech, I was a high school teacher. One of my core responsibilities as a teacher was simplifying and sequencing text written in complex technical language for learners to easily understand. I have also been a frequent contributor to a couple of open source software. Notable ones are ocaml.org and disease.sh.
Writing samples
Beginner friendly technical article written for freeCodeCamp
- Browser events explained in simple English
- How to add netlify form to a react app bootstrapped using create-react-app
Beginner friendly tutorials published on dev.to
- What is useRef hook and how do you use it
- Usecontext hook and context API. What are they and when do you use them
- What is useEffect hook and how do you use it
- Interview type coding challenges in JavaScript
- What is useEffect hook and how do you use it
Open source contribution
I helped improve firefox profiler setup instructions
Other useful links Resume portfolio
Project proposal
Project title
Create easy to learn tutorials for beginner users of Wechaty
Project approach
This is a high level overview of how I intend to approach this project. This is an evolving plan which will likely change pending feedback from stakeholders.
Seek to understand stakeholders
The first thing I will do is try to understand my audience. The tutorials are meant for absolute beginners who want to learn Wechaty but what else can we learn about them? If possible, I will seek answers to the following questions.
- What is their technical background?
- What demographic groups do they belong to?
- What problem are they trying to solve with Wechaty?
- What is their motivation for using/learning Wechaty? Is it for profit? Are they hackers doing it for fun? Are they using Wechaty for building school projects? Are they researchers/ academics? Is it a mix of the above categories of people?
It is important to learn as much as possible about your audience before writing tutorials so that it is tailored to their needs. Learning takes place much faster when it is structured from known to unknown and reference is made to what the learner already knows to explain a concept. It also ensures cultural sensitivity when giving examples especially in a global audience. The more you know about your audience the more relevant your examples will be. Develop content Work with the project volunteer to come up with the list of key things a total beginner who wants to learn Wechaty needs to know. Break those key learning areas into the smallest units possible. For example a learner might need to set up a development environment. Setting up a development environment is not the smallest unit possible. It can still be broken down. For example one might need a text editor, install software such as node or python, have access to certain platforms e.t.c.
Sequence content
Sequence the learning areas which have been broken down in the previous step in chronological order. For example, the knowledge, skills and competences attained in step A might be prerequisite for step B, that of A and B might be needed for step C and so on. If that is the case, it would make a lot more sense to sequence from A, to B then to C. Therefore sequencing the units appropriately from simple to complex, from known to unknown will make the learning process enjoyable.
Formulate instructional objectives
Turn those key learning areas into instructional objectives. The objective must be SMART. S - specific M - measurable A - attainable R - realistic T - within a time bound The smallest units in the previous sections can be amalgamated where necessary so as to make practical sense. A typical example of an instructional objective is: At the end of this section a learner should be able to set up a development environment for Wechaty. The objective is specific, measurable, attainable, realistic and within a time bound i.e. from the start of the section till the end. Achieving the above objective should contribute in a certain way to the overall objective of learning Wechaty so that a combination of all the small learning objectives will translate into the overall objective.
Map instructional objectives to learning activities
Identify practical, repeatable activities a learner can perform to achieve the stated objectives in the previous section. Let us say the main learning activity is building a chatbot using Wechaty. We would need to answer the following questions. What does building a chatbot using Wechaty entail? What steps should a learner follow when building a chatbot using Wechaty?
This should be done while paying attention to the objectives in the previous section to make sure they are being achieved as the learner goes through these activities. The cardinal reason for going through the tutorials is to achieve the objectives in the previous section which will ultimately translate into the overall objective.
Structure and write content
After outlining the activities in the previous section, we need to structure the content in a meaningful way. The proposed content structure and presentation is to split the tutorial into high level units/ sections. Each unit/section will have the following components. This is important because it ensures that anyone who has forgotten a specific concept can go to that specific section to remind themselves. Below are the proposed components of a unit. Each unit needs to have a link to the next and previous unit.
Section heading
The section heading should be a high level summary of what the learner will be doing in a particular section. It should capture the objective you wish to achieve by making the learner go through the activity.
Explanation
Immediately after the heading, there should be a brief explanation of what the learner will be doing in this particular section and why they are doing it. The focus should be on the learner. It is therefore important to use statements such as: In this section, you will declare a function which takes a string as argument and returns the number of characters in it. The focus here is on what the learner will do.
Prerequisites
After an explanation of what the learner will do in this section as articulated in the preceding subsection, there should be an outline of what the learner should know or have, to be able to complete this section successfully. For example the knowledge acquired in the preceding sections might be necessary to be able to complete this section. A learner might also need to have access to certain platforms such as whatsapp or facebook. This is where the prerequisites have to be clearly outlined. Prerequisites could also be software or other tools necessary to complete the section.
Steps
These are the actual steps a learner will have to go through. If it is a multi-step process, you can number them. For example step 1, step 2, step 3 and so on. There is no need to number if it is a single step process.
Expected output
What should happen if a learner successfully followed the steps outlined in the above subsection. An example of expected output is: After successfully installing software X, you should see it listed in the package.json file. We can also provide hints on possible challenges the learner might encounter in this section and how they can be fixed.
Fun Quiz
If possible, simple optional quizzes should be included at the end of each section to test the knowledge gained. This can boost the morale of the learner and give feedback about the progress they are making.
Additional resources
This is an optional section which points to additional resources a curious learner can explore to expand their knowledge about what has been covered in that particular section. It can link to Wechaty API if necessary.
Things to pay attention to while writing the tutorial**
- Use simple English that a non native speaker can easily understand without having to look up meaning of words or phrases
- Avoid long sentences.
- Minimize use of acronyms
- Avoid unnecessarily long paragraphs which might confuse learners
- Use formal language
- Be gender sensitive. Gender neutral language is better
- Pay attention to grammar and spelling
- Pay attention to technical accuracy
- Focus more on what the learner will do
Proposed timeline
Below is an estimate of the timeframe within which this project will be completed. It has been broken down into subtasks. It is worth pointing out that the processes below are not linear. They are iterative and cyclical. They can change as feedback is received from different stakeholders and incorporated in the project.
| Month | Activities | Stakeholders |
|---|---|---|
| 1 | <ul> <li> Technical writer learns Wechaty </li><li> Engage stakeholders to understand the Wechaty community </li><li> Develop outline of tutorial content </li><li> Develop learning objectives </li><li> Formulate tutorial structure at a higher level </li><li> First tutorial draft </li><li> Release first draft and take feedback </li></ul> | <ul> <li>Volunteer</li><li>Contributors</li><li>Users</li> </ul> |
| 2 | <ul> <li> Receive feedback from stakeholders about first draft </li><li> Incorporate feedback given for first draft </li><li> Release second draft </li><li> Incorporate feedback from stakeholders </li><li> Test the tutorial with volunteer beginners </li><li> Incorporate feedback from volunteers </li><li> Release final version of tutorials </li></ul> | <ul> <li>Volunteer</li><li>Contributors</li><li>Users</li> </ul> |
| 3 | <ul> <li> Audit Wechaty website </li><li> Propose changes to the volunteer mentor </li><li> Make improvements to the Wechaty website </li><li> Get feedback </li><li> Incorporate feedback </li> | <ul> <li>Volunteer</li><li>Contributors</li><li>Users</li> </ul> |
Proposed budget
The proposed budget for the entire project is 5000USD(Negotiable).
Soumi Bardhan: Interactive tutorials for newcomers