You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[JackieBinya](https://github.com/JackieBinya) is a software developer, technical writer, cloud enthusiast, and a Google Season of Docs 2020 participant.
[Nimish Bongale](https://nimishbongale.github.io/) is a Technical Writing Intern at Creative Commons. He goes by `@nimishnb` on the CC Community Slack workspace. Nimish is currently developing the website and documentation for [CC Vocabulary](https://opensource.creativecommons.org/cc-vocabulary/) as part of [Google Season of Docs 2020](https://developers.google.com/season-of-docs).
Radek Czajka is a developer based in Warsaw, Poland. Long-time lead developer at [Modern Poland Foundation](https://nowoczesnapolska.org.pl) and its [WolneLektury.pl](https://wolnelektury.pl) free internet library. Free software enthusiast, considers NC-SA the worst license.
title: Vocabulary Site & Usage Guide Introduction (GSoD'20)
2
+
---
3
+
categories:
4
+
cc-vocabulary
5
+
gsod
6
+
gsod-2020
7
+
---
8
+
author: nimishbongale
9
+
---
10
+
series: gsod-2020-vocabulary-usage-guide
11
+
---
12
+
pub_date: 2020-10-02
13
+
---
14
+
body:
15
+
Hey there! I'm Nimish Bongale, a Technical Writer & Software Developer based out of Bangalore, India. My other hobbies include playing chess and the guitar. I look forward to build the CC Vocabulary site and usage guides as a part of GSoD'20.
16
+
17
+
## But what is GSoD?
18
+
19
+
GSoD, or Google Season of Docs, is a program that stresses on the importance of the documentation aspect of Open Source projects. It invites technical writers from across the world to submit proposals based on projects floated in by the participating Open Source Organisations. The selected technical writers then work with the their respective organisations and look to complete their work by the end of their internship period. More information about the same can be found [here](https://developers.google.com/season-of-docs).
20
+
21
+
Let's talk a bit about my project, shall we?
22
+
23
+
## Vocabulary Site & Usage Guide
24
+
25
+
### Introduction
26
+
[CC Vocabulary](https://github.com/creativecommons/vocabulary) is a cohesive design system & Vue component library to unify the web-facing Creative Commons. It's currently comprised of 3 packages, namely Vocabulary, Vue-Vocabulary & Fonts. My contribution to this project would majorly involve building the landing site for CC Vocabulary, and refactor the documentation wherever necessary.
27
+
28
+
### What drives me
29
+
Documentation is one of the primary reasons which determines how successful a certain open source library will be. The major question that developers think of while choosing a suitable tech stack to build their applications is:
30
+
31
+
- Is the library _well documented_?
32
+
- Is it _well maintained_?
33
+
- Does it have some _considerable usage and error support_?
34
+
35
+
These are exactly the questions I should be asking myself while going about this project idea.
36
+
37
+
As aforementioned, there is an immanent need to have a concise and consolidated documentation. The lack of documentation hurts the future perspectives of open source applications, and is by far, an essential and non-negligible component. Linking to these documentations should be an appealing home page, which captures the interest of the people in an instant. The documentation should be well organised, thereby enabling a seamless flow through it.
38
+
39
+
### Tech stack of the project
40
+
We have decided to move forward with [Vuejs](https://vuejs.org/) for building the site, and continue work on the existing [storybooks](https://storybook.js.org/) of Vocabulary, Vue-Vocabulary and Fonts. Storybookjs has had some great improvements in recent times, and the new addons that are offered will greatly support my work. Besides these, I will also be using [StackEdit](https://stackedit.io/) to write and share Markdown files of my writings.
41
+
42
+
### Progress - Baby Steps
43
+
I have contributed to CC in the past. It would now be my first time contributing to a specific project within CC, while being a member of CC Open Source. Some tasks that I've been able to initiate/accomplish so far:
44
+
45
+
- Look at Open Source documentation conventions, and see if we violate any.
46
+
- Understand the level of existing documentation currently present in our storybooks.
47
+
- Discuss about the Monorepo migration and help out with the implementation.
48
+
- Migrate `storybookjs` to the latest version.
49
+
- Implement `addon-controls` for vocabulary.
50
+
- Design the vocabulary site.
51
+
- Promote the involvement of CC Open Source in [Hacktoberfest](https://hacktoberfest.digitalocean.com/) 2020.
52
+
53
+
### What did I learn?
54
+
55
+
- Design is more than just picking colors and placing components on a grey screen.
56
+
- It's important to read your own writings from an unbiased perspective to actually understand how well it would be perceived.
57
+
- Interacting with your mentor on a regular basis is of the absolute essence.
58
+
- Publishing to [npmjs](npmjs.com) is not difficult!
My name is Jacqueline Binya. I am a software developer and technical writer from Zimbabwe. I am going to write a series of blog posts documenting my experience and lessons as I contribute to the [Creative Commons WordPress Base Theme(CC WP Base Theme)](https://github.com/creativecommons/wp-theme-base) during the [Google Season of Docs (GSOD-2020)](https://developers.google.com/season-of-docs) as a technical writer.
16
+
17
+
## What is Google Season of Docs?
18
+
19
+
The Google Season of the Docs was born out of a need to improve the quality of open-source documentation as well as to advocate for open source, for documentation, and for technical writing. Annually during the GSOD, technical writers are invited to contribute to open-source projects through a highly intensive process geared at ensuring that the technical writers and the projects they contribute to during GSOD are a good fit, after that has been determined GSOD then resumes.
20
+
21
+
## Building the docs
22
+
The CC WP Base theme is a WordPress theme used to create front-facing Creative Commons (CC) websites. My task is to collaborate with the engineering team to create community facing docs for the theme.
23
+
24
+
### Guiding principles
25
+
The docs should be inclusive meaning: they should be written in an easy-to-understand manner taking care to avoid the use of excessive technical jargon, they should be accessible and they should have support for internationalization. We hope to provide our users with a smooth and memorable experience whilst using the docs hence the docs site should be fast and easy to navigate.
26
+
27
+
### Technical stack of the project
28
+
We decided to build the docs using [Jamstack](https://jamstack.org/), to be specific we are using [Gridsome](https://gridsome.org/) a static generator for [Vuejs](https://vuejs.org/). We are using Gridsome as it is highly performant, and it also integrates smoothly with the [CC Vocabulary](https://cc-vocabulary.netlify.app/). Gridsome also has out-of-the-box support for important features like Google Analytics and [Angolia](https://www.algolia.com/), these features will obviously be useful in future iterations of the docs. To quickly scaffold the docs we used a Gridsome theme called [JamDocs](https://gridsome.org/starters/jamdocs/).
29
+
30
+
### Progress
31
+
Currently, the project is on track. As it's been stated we are creating the docs collaboratively. The very first step in our workflow is to create draft content using Google docs. That task is assigned to me, it involves doing lots of research, reading and also testing out the theme. Afterwards, my mentors Hugo Solar and Timid Robot Zehta then give me feedback on the draft. Then I implement the feedback and continuously work on improvements. The final step is migrating the approved draft content to the docs projects in markdown format.
32
+
33
+
### My lessons so far:
34
+
- Always ask questions: frankly, the only way you can create good content is when you have a solid understanding of the subject matter.
35
+
- It's better to over-communicate than under-communicate especially when working in a remotely, this is especially more important if you encounter blockers whilst executing your work.
36
+
- Push that code and open PR quickly and then go ahead and ask for a review don't procrastinate this will ensure fast turnover you get feedback quickly and can work on improvements.
37
+
38
+
39
+
_Thank you for reading, watch out for the next update which will be posted soon._
Copy file name to clipboardExpand all lines: content/contributing-code/contents.lr
+12-12
Original file line number
Diff line number
Diff line change
@@ -17,19 +17,19 @@ We make extensive use of issue labels to designate the priority, status and begi
17
17
18
18
-**Issues available for community contribution:**
19
19
- The following tags mark issues that are open for community contribution:
20
-
-`help wanted`: Open to participation from the community but not necessarily beginner-friendly
21
-
-`good first issue`: Open to participation from the community and friendly towards new contributors
20
+
-<spanclass="gh-label friendliness">help wanted</span> : Open to participation from the community but not necessarily beginner-friendly
21
+
-<spanclass="gh-label friendliness">good first issue</span> : Open to participation from the community and friendly towards new contributors
22
22
- You do not need our permission to work on one of these issues.
23
-
- You may work on an issue labeled `good first issue` even if it's not your first issue.
23
+
- You may work on an issue labeled <spanclass="gh-label friendliness">good first issue</span> even if it's not your first issue.
24
24
***Issues not available for community contribution:**
25
25
- The following tags mark issues that are _not_ open for community contribution:
26
-
-`🔒 staff only`: Requires infrastructure access or institutional knowledge that would be impractical to provide to the community
26
+
-<spanclass="gh-label friendliness">🔒 staff only</span> : Requires infrastructure access or institutional knowledge that would be impractical to provide to the community
27
27
- Do not work on these.
28
28
-**Issues not ready for work:**
29
29
- The following tags mark issues that are _not_ open for community contribution:
30
-
-`🚧 blocked`: Blocked by other work that needs to be done first
31
-
-`🧹 ticket work required`: Needs additional work before it is ready to be taken up
32
-
-`🚦 awaiting triage`: Has not been triaged by a maintainer
30
+
-<spanclass="gh-label status-neutral">🚧 status: blocked</span>: Blocked by other work that needs to be done first
31
+
-<spanclass="gh-label status-dark">🧹 status: ticket work required </span>: Needs additional work before it is ready to be taken up
32
+
-<spanclass="gh-label status-darker">🚦 status: awaiting triage</span>: Has not been triaged by a maintainer
33
33
- Do not work on these.
34
34
-**Issues without any of the above labels:**
35
35
- These issues _may_ (or may not) be open for contribution.
@@ -38,9 +38,9 @@ We make extensive use of issue labels to designate the priority, status and begi
38
38
You can use our [Issue Finder tool](/contributing-code/issue-finder/) to find a good issue that matches your skills and familiarity with our software and community.
39
39
40
40
Some helpful saved searches on GitHub than can assist with finding an issue:
41
-
-[issues labeled "good first issue"](https://github.com/search?q=org%3Acreativecommons+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+-linked%3Apr)
Check the issue comments/labels to see whether someone else has indicated that they are working on it. If someone is already working on it and there has been activity within the last 7 days, you may want to find a different issue to work on.
46
46
@@ -60,7 +60,7 @@ If you want to work on something that there is no GitHub issue for, follow these
60
60
61
61
1. Create a a new GitHub issue associated with the relevant repository and propose your change there. Be sure to include implementation details and the rationale for the proposed change.
62
62
* We are very reluctant to accept random pull requests without a related issue created first.
63
-
2. The issue will automatically have the `not ready for work` label applied. Wait for a project maintainer to evaluate your issue and decide whether it's something that we will accept a pull request for.
64
-
3. Once the project maintainer has approved the issue and removed the `not ready for work` label, you may start work on code as described in the "Contribution process" section above.
63
+
2. The issue will automatically have the <spanclass="gh-label status-darker">🚦 status: awaiting triage</span> label applied. Wait for a project maintainer to evaluate your issue and decide whether it's something that we will accept a pull request for.
64
+
3. Once the project maintainer has approved the issue and removed the <spanclass="gh-label status-darker">🚦 status: awaiting triage</span> label, you may start work on code as described in the "Contribution process" section above.
65
65
66
66
When in doubt, ask a question on [one of our community forums](/community/).
0 commit comments