This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Global Wordnet Association
- Technical writer:
- Yoyo Wu
- Project name:
- Wordnet Structure
- Project length:
- Standard length (3 months)
Project description
Why this project
As a technical writer majoring in Linguistics, I am happy to find such a project, with the idea of linking different languages together with a unified semantic-conceptual framework, and has been applied to real world business such as Google Translate. I would like to contribute to the docs of this project to make it more user-friendly to the audience.
Issues
I have gone through the original document, and think we can improve it by solving below issues: Lack of an Overview section at the beginning to introduce the basics of wordnet, which will be useful to the novice. Although all the relations in the wordnet are rolled out in a unified template, some relations lack necessary info such as examples and tests, which is distributed in Princeton Wordnet webpage, EuroWordnet general guidelines and other resources. The Short definition and Definition, Short example and Example lack unified sentence pattern, since Short definition and Short example are the callouts when user’s mouse hover over the particular relation, Definition and Example serve the main role of introducing the relation, they should be structured in unified but different patterns from their short counterparts. The Tests are from EWN, but the conditions block should be put ahead of the main test body, since users will always look at the conditions first to decide whether their linguistic data matches the conditions, then to take the test. The test body is also not that straightforward with lots of linguistic acronyms. The content of Comments section is diversified, sometimes it stresses a particular point of the definition, sometimes it states project-specific details. I think we should set a standard for this section, Move info about specific projects to the Project-specific Names section should be more convenient for users. The Project-specific Names section summarize the relation name in all projects, this section needs to be reviewed since mismatch errors occur. Need to link the Glossary of terms directly to the document, and to add all the acronyms and terms which may be unfamiliar to the novice.
Guidelines
I would also like to discuss below two topics with the project team before drafting the docs, the conclusion received will serve as the general guidelines for the entire project.
About the audience Here is a real example of myself, although I am a linguistic major, when I first come across the original document, I don’t know what “synset” means, it’s on the Princeton Wordnet webpage that I find the meaning of synset.
So at first we need to figure out the knowledge structure of potential audience, If we cannot ensure all the audience is equipped with relevant knowledge, then at least we need to add an Overview section, link the Glossary of terms and other related resources to guide them through wordnet and its related projects. We should always keep this assumption in mind during the entire documenting process,
About the function of the docs According to my understanding, the goal of wordnet structure docs is to help users get familiar with all the relation types in wordnet, and users can group words into those relations based on the info provided. However, the original docs look more like extracts of academic papers. If the purpose of the docs is for academic reference, that’s okay, but if it serves the goal of guiding users, then there must be trade-offs between academia and utility.
Benefits
I can help translate the Chinese version of the docs. I have experience of translating linguistic papers from English to Chinese. I can help format the docs, I know the basics of HTML/CSS and can help to make the docs webpage look better such as adding a side navigation bar. I can help draw some flowcharts using Visio or Mermaid if the flowcharts can help users better understand the relations.
Milestones / Time / Goal
- Week 1: Discuss and settle down the goal, workflow and working plan with the project team.
- Week 2: Settle down the docs outline and write the Overview section.
- Week 3 – Week 4: Write the Constitutive relations part.
- Week 5 – Week 6: Write the Other and Domain relations part.
- Week 7 – Week 8: Write the Role relations part.
- Week 9: Write the remaining three relations and update the glossary.
- Week 10: Translate the Chinese version if needed.
- Week 11: Revise the format of the docs.
- Week 12: Final check and summarize this project.