I procrastinated a lot on this blog because I didn't know where to start, but anyway, I was assigned several tasks at work last year, which resulted in me writing a lot of documentation. One particular doc had to be read in order, from top to bottom, and I didn't want to split it into different docs... See what I'm trying to get at? I'm having problems organizing docs at work, and guess what other project was having the same problem? Telescope!
Google has a '20% time' rule so I decided to use my time on Telescope.
“We encourage our employees, in addition to their regular projects, to spend 20% of their time working on what they think will most benefit Google,” founders Sergey Brin and Larry Page wrote in their IPO letter. “This empowers them to be more creative and innovative. Many of our significant advances [like AdSense and Google News] have happened in this manner.”
I was eager to get started, so I went back to the age-old issue #290 I filed years ago. I had to remind myself what had been completed for this issue because although I initially suggested using Docusaurus, we found out Gatsby.js supported adding markdown pages, so I started working on just the About page to have something similar to Docusaurus but use Gatsby plugins instead. Unfortunately, we were stuck on the design and ran out of time to complete it.
When the 2.0 team was porting our Gatsby.js frontend to Next.js, we also found out that Next.js also supports MDX so Chris converted my work on the About page and implemented it in Next.js.
Come Winter 2022, I decided to resurrect the issue and tried to convenience the team (mainly myself) that it would be fun. Of course, I didn't expect any interest in this because students typically want to write code and contribute to an area of their interest which is rarely maintaining documentation.
I initially put up a PR that created a microservice for the docs using Next.js, MDX, and Tailwind CSS. Yes, this was my terrible attempt at getting Tailwind CSS into Telescope, but we already had a Next.js frontend, and it didn't make sense to have two Next.js projects to maintain. My second PR used Docusaurus, but I introduced too many parts, which made it extremely difficult to review. I added:
- The Docusaurus project itself
- Dockerized it
- Attempted to hook it up to Traefik
- Attempted to hook it up to Nginx
In the end, it wasn't working as expected, so I made a third PR. Smaller PRs are easier to review and understand. Unfortunately, I got carried away with my second PR because I didn't want the Docusaurus feature to turn out like my Gatsby About page, where only one part of it was implemented, and the rest was unfinished.
I had thought of an MVP for Docusaurus in my head, but now I'm gonna write it down here:
- Docusaurus website contains all the Telescope docs
- Docusaurus website is accessible on staging and production at http://dev.telescope.cdot.systems/docs and http://telescope.cdot.systems/docs, respectively
- Each doc shows when the doc was last modified and by whom.
As you can see, we're already almost there. I also filed many nice to have issues and was surprised at the number of contributors that rallied behind the Docusaurus feature. I try my best to keep the Docusaurus Project Board up to date because I could quickly lose track of everything since I didn't do all the work.
For the 2.7 Release, we closed 20 issues and PRs related to Docusaurus! Thank you to our contributors, reviewers, and project board creator. In no particular order:
Top comments (0)