This is the joint project proposal for Improve the Introduction and Explanations secondary project under Google Season of Docs 2021. It is estimated that this project will take approximately 06 weeks.
Technical writers
Mukosa Joseph Mawa
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.
Chris Estepa
Currently, I am a full-time technical writer supporting users how to use their applications by creating how-tos, video tutorials, training materials, FAQs, and requirement analysis documents, among others.
I love technical writing because it being a combination of communication and technology allows me to write and provide support to users, especially newbies. I know the pain and frustration of not getting the information that the users need and now, I am here to help users through my writing. Through GSOD and Wechaty, I will be able to engage more users to have a wonderful experience with their Wechaty chatbots.
Proposal Video Presentation
Project title
Improve the Introduction and Explanations sections of wechaty.js.org.
Project scope
The scope of this project is limited to improving the Introduction and Explanation sections of the wechaty.js.org website.
Project goal
Our goal is for users not to lose interest upon landing on the Wechaty site. We plan to make the Introduction section succinct and engaging by also showing them what they are looking for and what they will be getting when they start creating their very own chatbots. More useful information will be shown in Explanations, to help users further understand and appreciate what Wechaty can do for them. We aim to have a strong documentation that would stand the test of time.
Analysis of the Introduction and Explanations sections of wechaty.js.org
After the analysis of the Introduction and Explanations sections, the following issues have been identified:
- There are irrelevant content which are not suitable for the introduction.
- There are missing and incomplete pieces of information.
- Provided explanations are not comprehensive and incoherent.
- The sections are poorly structured.
- There are lots of typos and grammatical errors.
- The section is too long for an introduction.
- The sections are too nested and as a result, hiding certain information which should be on the front page.
- Some pages lack visual representation that would be comprehensive to users.
- Some information may not be understood easily by non-technical users.
- Some pages need a more straightforward explanation. Some descriptions in the explanations are not comprehensive There are many blank and orphaned pages.
Purpose of Introduction section of wechaty.js.org
The introduction section of wechaty.js.org serves the following purposes:
- Help technical and non-technical people understand what Wechaty is.
- Help potential individual and institutional users of Wechaty understand some of the business challenges/problems they can solve by using Wechaty.
- Help total beginners understand how to start using or learning Wechaty.
- Helps the user understand why and what sets Wechaty apart from other chatbot makers.
Purpose of explanation section of wechaty.js.org
The explanation section of wechaty.js.org serves the following purposes:
- Describe other concrete pieces of information which have not been covered in other areas of the documentation in an easy manner understood by all types of users esp. non-technical users.
- Deepen and enrich users’ knowledge of Wechaty by providing alternative/contrary viewpoints and approaches than what has been presented in other sections of the documentation.
- Educate users and arouse their interest by showing the technical, non-technical and business side of Wechaty which have not been covered in other sections of the documentation.
Project approach
This is a brief overview of how we intend to approach the project in an attempt to solve the identified problems. This plan will change as feedback is sought from the stakeholders. We propose the current Introduction section to be replaced by the following content. This however will mostly depend on the final decision on how the entire wechaty.js.org is to be designed, or structured since there are quite a number of technical writers writing proposals on how to improve the different sections of wechaty.js.org.
Proposed content for Introduction section
It is proposed that the following questions should be used as guide when writing the introduction section:
What is Wechaty?
This section should include the following:
-
Brief introduction to what Wechaty is
This must be written for both technical and non technical audiences. Meaning of acronyms such as IM, SDK, etc. should be made explicitly clear by linking to their full versions. Thus, whoever is not familiar with it can look it up and understand what is being talked about.
-
Who are the People/Companies behind Wechaty?
Who are the original creators of Wechaty? When was it created? Are there companies, individuals, government, and entities supporting the development of Wechaty? Are there companies who have supported the development of Wechaty in the past or planning to provide support in the future?
-
How many releases have been made since its creation?
What is the current stable version of Wechaty? How many releases have been made since its creation? Are there plans for another major release? Are there ongoing major projects around Wechaty at the moment?
-
Original motivation for creating Wechaty
What was the story behind Wechaty? Every software project must seek to provide a solution to a business or societal problem. What were the founders of Wechaty seeking to solve by starting Wechaty? This area will need a lot of input from the creators of Wechaty.
-
The long term Vision and Mission of Wechaty
This must be well thought of because it will give a sense of confidence to users of Wechaty about long term support and development. A person who wishes to solve a business problem using Wechaty should feel confident that there are visionary people committed to the long term development of the software their business runs on. This area will also need a lot of input from the creators of Wechaty.
What can you do with Wechaty?
This section should comprehensively cover the following:
-
What problems can businesses/ individuals solve with Wechaty?
This section will give a Wechaty user the motivation to learn and use Wechaty if it is properly articulated. It gives users a sense of purpose if they notice that Wechaty is capable of solving a business challenge that they are facing.
- What business problems have been solved by using Wechaty?
- How has Wechaty solved the problems of people/businesses?
Who is using Wechaty?
In this section, we need to get testimonials from people/businesses who have used Wechaty before and how they find Wechaty. What are they saying about Wechaty? How has Wechaty solved their problem? This section should seek to comprehensively answer the following questions:
- Which companies/individuals are using Wechaty?
- Are there testimonials from users of Wechaty on the value it has delivered to their businesses? Here, we also need to provide links to the live Projects built using Wechaty.
Proposed content for Explanations section
The Explanation section is primarily for broadening the documentation’s coverage of the different topics therefore its content will very much depend on the other sections of the documentation. The outline below is not cast in stone. Some items might be removed or added as the different projects evolve.
It is proposed that the following should be used as guide when writing the Explanation section:
-
Overview
This will be discussed based on a high level perspective but in a way that most users (esp. newbies) would understand. This page will let users know other information that they have to know. In order to do this, we will need more information from the subject-matter experts.
-
Lifecycle
A concise explanation on the typical phases in the development (including some activities and deliverables being done) of Wechaty to inform users, sponsors, and investors about what is happening with the project.
-
Architecture
A short but thorough chatbot architecture must be explained here. A diagram would also make the explanation clearer.
-
Alternatives
In this section we shall present alternatives to Wechaty.
-
Testing
An overview on how we perform testing is imperative so that users would know what is being tested, what to expect and not to expect, and learn more about the bugs and defects that we encounter while using Wechaty. Other types of issues can be discussed here, including the types of actions and expected output or solutions. Triaging of bugs and issues may be clearly specified here, by highlighting the issues and the bugs that need intensive testing. Priorities may also be established including the severity of the bugs, whereby the Wechaty team would know what the problems are and how to deal with them.
-
DevOps CI/CD
We can explain how Wechaty uses and benefits from DevOps and CI/CD processes. Some information is needed from the SMEs to expound this.
-
Software Development Kit (SDK)
Conversational and Robotic Process Automation SDK information will be discussed here.
-
Troubleshooting
In this section, we will determine and pinpoint the most difficult and most common problems that users encounter. On the spot solutions are provided here to enable users to learn what to do first hand upon encountering issues.
Proposed solution
We propose to improve the structure and documentation approach of the Introduction and Explanations sections. These are critical sections that any user must read to fully understand what Wechaty is all about.
Other to-dos or suggestions
- Include a diagram, workflow, or any other visual representation to make the sections more comprehensive and informative.
- Include Other Related Pages links for better and easier navigation.
- Include a Contact Us page that contains some support links or a form where users can write their questions and suggestions.
- Include testing and friction logs that will serve as good references in the future.
Things to pay attention to while writing the introduction and explanations sections
- Use simple English that a non-native speaker can easily understand without having to look for the meaning of words or phrases.
- Avoid long sentences.
- Minimize use of acronyms and initialisms.
- Avoid unnecessary long paragraphs which might confuse beginners.
- Use formal language.
- Be gender-sensitive. Gender neutral language is better.
- Pay attention to grammar and spelling.
- Pay attention to technical accuracy.
Proposed timeline
It is estimated that this project will take six weeks. Below is the estimated timeline and the subtasks which will be accomplished. It is worth pointing out that the processes below are not linear. They are iterative, cyclical, and can change whenever feedback is received from different stakeholders and therefore, incorporated in the project.
-
Week 1: Hiring process
- Refining proposal to meet stakeholder needs/expectations
-
Week 2: Introduction
- What is wechaty section
- What can you do with wechaty section
- Who is using Wechaty section
- Integrating feedback from stakeholders
- Miscellaneous
-
Week 3: Introduction
- Getting started with Wechaty
- Main concepts in Wechaty
-
Week 4: Explanation
- Life Cycle
- Architecture
- Testing
- Troubleshooting
-
Week 5: Explanation
- DevOps CI/CD
- SDK
- Troubleshooting
-
Week 6: Project Evaluation
- Project Evaluation
Project budget
The project budget is 1000USD which will be shared equally between the two technical writers
Google Season of Docs 2021 Team Proposal - Volunteering