This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Creative Commons
- Technical writer:
- Project name:
- Vocabulary Usage Guide
- Project length:
- Standard length (3 months)
Vocabulary has immense potential to be used as a primary UI component library for website building. What It needs is a robust yet layman-friendly how-to guide. Important developer information such as component guides, usage specifications and configuration tweaks form an essential part of any documentation. This will not only encourage existing users to get a feel of how vocabulary continues to grow and reach new milestones, but also promote the usage of Vocabulary in comparatively newer projects. The desired outcomes of my stint as an intern would not only involve penning out a no-nonsense guide to using the pre-existing components but also the designing and developing a home page (leading to an integrated documentation for each) for Vocabulary, Vue-Vocabulary and Fonts.
The Problem: Documentation is one of the primary reasons that determines how successful a certain open source library will be. The major question which developers think of while choosing a suitable tech stack to build their applications is “Is the library well documented? Is it well maintained? Does it have some considerable usage and error support?”. These are exactly the questions we should be asking ourselves while going about this project idea. From the software engineering perspective:
Requirement Analysis: There is an immanent need to have a concise and consolidated documentation for our needs. 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.
Specifications: Depending on the requirements, specifications can be decided. The content in the documentation can be formed from data present in the CC netlify websites, along with some inspiration from well known documentations like semantic-ui, scikit-learn, numpy, bootstrap etc. The output of this task would be the required landing page and the complete documentation guides.
Some general issues connected with Vocabulary, Vue-Vocabulary and Fonts currently:
There’s an absence of documentation; and even if there is some, parts of it are scattered throughout the netlify websites. This does not enable users, developers or external contributors from using our library.
To get to a certain component and copy its corresponding code takes additional clicks. A simple Google search for something like “Tabs component CC Vocabulary” does not return the desired information. A Search option within the documentation guides would greatly improve UX.
A bit more textually detailed description for the components, describing the unobvious details.
No live run option. A live run is supported by various sites like JSFiddle, which enables developers to get a feel of the component without running an entire application to see it work.
There are multiple solutions possible. However, I’ll touch upon a few here, and present my final solution in the conclusion part:-
= Using readthedocs readthedocs is a well known solution to write documentation for open source libraries. It is based off of Sphinx, the python documentation tool.
- Widely accepted form of documentation generation, used by organizations like Ethereum (Solidity).
- Optimally structured documentation.
- Free static hosting.
- Lack of absolute control over the styling.
= Using Sphinx We could natively use sphinx for the documentation part as well, it provides good features for all our purposes.
- The most popular python tool for documentation.
- Has support for documentation searches as well.
- Default CSS can be overridden with a custom one; some control over HTML using .rst files.
- Would involve coding in python and restructured text format (.rst) which will be a deviation from the suggested project languages.
= Using Jekyll Themes Jekyll themes are integrated within github pages, and there are pre existing templates which could be customized depending on our needs.
- Ready made documentation themes for all purposes.
- Default CSS and styles may be overridden with custom ones, control over HTML as well.
- Pulls the default Primer CSS for building the pages.
- Easy integration with GitHub pages.
- May not provide the best documentation structuring.
=Using GitHub pages The standard github pages to build our static site (HTML, CSS, JS).
- Full control over almost everything in question.
- Maximum flexibility in deciding layout, colours and styles.
- Easy usage of Vocabulary components.
- Easy embedding of code snippets, and live run links.
- May be a more time consuming approach.
= Using Haroopad This gives an alternative markdown solution instead.
- Would involve minimum fiddly coding.
- Focus would be on writing the documentations perfectly.
- Lack of control over CSS.
- May or may not have the best community support.
- May not support MDX.
= Using MKDocs This gives another alternative markdown solution instead.
- Would involve minimum fiddly coding (again).
- Write more, Code Less approach.
- Lack of control over CSS.
- May not have the best community support.
- Uses python; there may further arise the need of spinning up an Amazon S3 instance.
= Using VueJS +StorybookJS This approach is commonly used across Vocabulary and its sister repositories.
- Sticking to technologies which are guaranteed to work just fine, given past work experiences.
- Familiarity with the code base.
- No competent technology in this space.
- Simpler options may also be present for the same purposes.
In conclusion, I’d like to think the approach involving the VueJS+Storybook approach (HTML,CSS,JS) seems like the most suitable, given that I’m comfortable with it as well. However, this would also mean that we won’t be going completely out of our way in developing this application. It would also be fairly straightforward to use CC-Vocabulary components. However, to decide the structure of the documentation, we should definitely consider the way the content is divided among subheadings in the readthedocs documentation. I was impressed with the Semantic-UI website (which uses StoryBook) as it has a minimalist look and one can easily get to know what they want after just a few clicks. Apart from Semantic-UI, I also had a look at Material Design, Primer, Bootstrap, Carbon Design etc. to be used as UI styling guides and design systems for my work. We can also look up on ready-made Jekyll documentation themes also for inspiration for the same.