lab 6 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Lab 6
Due Date
Friday October 28 by Midnight.
NOTE: you have an extra week to complete this lab, which is also longer than previous labs. Please don't leave it until the last minute. Start it now and iterate on it over the next few weeks.
Overview
Over the next two weeks, we are going to extend our SSG projects by exploring the features of a popular SSG, Docusaurus. We'll also use this lab in order to learn how Docusaurus works. Seneca is in the process of converting all of our C/C++ curriculum to an OER version based on Docusaurus, and in the second half of the course, you'll have a chance to contribute to this project.
Docusaurus is a React-based static site generator built and maintained by Facebook. It helps projects document their technology for users and developers, without having to put a lot of effort into creating a full website. Lots of projects use Docusaurus for their project documentation, for example Jest, Redis, creact-react-app, Home Assistant, React Native, and many more.
This lab will help you practice the following:
- setting up and learning the Docusaurus project for a documentation site
- evaluating existing open source projects for inspiration and ideas when building your own solutions
- prototyping a new feature in your SSG
- estimating and planning a change to your software
- implementing a working proof-of-concept quickly
- planning future work via Issues
Step 1: Learning Docusaurus
Please read the Docusaurus Docs and Installation instructions. Create a new Docusaurus website and repo and publish your sample site. NOTE: you don't need to write any documentation, just learn how the tool works, get it working and hosted on your site's GitHub Pages.
When you're done, you should have two URLs:
- A new GitHub Repo: https://github.com/{your-username}/{your-docusaurus-sample-repo}
- A new GitHub Pages hosted Site: https://{your-username}.github.io/{your-docusaurus-sample-repo}
Step 2: Copy a Cool Feature from Docusaurus
Docusaurus is full of cool and interesting features. In the open source world, it's fine to copy where licenses allow it. Docusaurus' License allows you to "use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software," as long as you accept the license.
You are asked to pick a feature of Docusaurus that you think is interesting. You are free to pick whatever feature you like based on Docusaurus, but here are some suggestions:
- Search Engine Optimization (SEO), including
metatags in the HTML head - Improved Accessibility of generated HTML
- Support for React components
- Themes
- Plugins
- Configurable Sidebar (i.e., table of contents)
- Full Markdown support (e.g., swap out your basic version for an open source library/module that does it fully)
- Syntax Highlighting for code blocks
- Search
- Static Assets for images, stylesheets, etc.
- Markdown Frontmatter support
- Blog posts in addition to Pages
Step 3: Plan your Feature and File Issues
Plan out how you'll implement a prototype of this feature using GitHub Issues. File Issues in your SSG repo to document what needs to be done and ideas on how you'll approach the work. The smaller you can make each Issue, the easier it will be to fix them.
Next, prototype the feature in your SSG project. Prototyping means building just enough of a feature in order to understand how the finished version might work. It doesn't need to be 100% complete or perfect. With a prototype, going fast is more important than being meticulous and detail oriented.
Create a branch and start implementing your code, committing to git as you knock-off various bits of the work.
When you're done, you should have something that can be squashed and merged into your default branch. It can be a simple proof-of-concept (missing key elements), as long as it works and proves your idea.
Step 4: File Follow-Up Issues
The chances of you being able to write the entire feature in the time you have are slim. By the end of the two weeks, for any aspects of the feature that you can't get done, file more Issues to be fixed later on. Challenge yourself to stay on schedule, and convert unfinished work into Issues to be solved in subsequent releases. Figure out what you need to cut in order to ship something on time. Shipping on time is more important than being perfect and never shipping. Software is never done, so it's important to learn to embrace the chaos of rolling releases and ongoing bug fixes.
Step 5: Write a Blog Post
After you're all done, write about the experience. Here are some ideas to touch on in your post:
- How would you describe Docusaurus to a friend who has never used it before?
- What was it like to set up a Docusaurus project?
- Which feature did you decide to copy from Docusaurus? Why did you choose it?
- How did you approach adding it to your SSG?
- How did the planning experience compare to the actual work? How close were you in your estimation about what you could get done vs. what was left for the future?
- Talk about your prototype of the feature: what does it do?
- What are your next steps for the feature and how can people get involved to help you move it forward (e.g., issues you've filed)
Remember, make sure you include URLs to everything you discuss.
Submission
When you have completed all the requirements above, please add your details to the table below.