Motivations

This project draws inspiration from Joel Spolsky’s insightful blog post on the importance of a development abstraction layer. While the article was intended mainly for a project manager, I think it applies well even for a developer relations role. Eliminating any obstacles that hinder programmers from doing their job is super important. And often accessing relevant documentation promptly is one of them!

As a developer advocate, I understand the need to make it straightforward for newcomers to grasp the concepts and utilize the functionality being described. But along with creating the tutorial, I pondered, why not also explore ways to enhance documentation and improve accessibility? The features incorporated into this website are an experimental exploration of this very idea. Here are some of them:

  1. Search Feature: As a developer, I frequently find myself recalling that I’ve come across a particular API or method in a tutorial but struggling to pinpoint where. A search feature would be incredibly helpful, eliminating the need for me to remember the exact location of each section.
  2. Table of Contents: Include a sticky table of contents for easy navigation through the material that can be collapsed by the reader.
  3. Sidenotes: Utilize the large unused margins on the left and right to incorporate sidenotes. These sidenotes can be used to provide quick explanations of code aspects without causing distraction or affecting their flow. Developers may choose to read or skip them based on their preferences (see example on right).
Collapsible sidenote
  • df.age.isnull(): This part of the code returns a boolean series where each value is True if the corresponding value in the age column of df is missing, and False otherwise.

The above 3 features allow you to achieve the skimmable principle, as outlined in Write the Docs.

4. Callouts

Use callouts to highlight particularly important or interesting points within the article.

  1. Report an Issue: Offer a user-friendly “report an issue” button that directs readers to the GitHub repository’s issues tab, if they face any difficulties while navigating the tutorial/docs (See participatory principle from Write the Docs.
  2. Visual Elements: Enhance engagement by integrating mermaid diagrams and Plotly for visual representation and interactivity. This approach can encourage interaction with the content, transforming readers into participants.
  3. A dark mode! 😎

What are your thoughts on these ideas?

Back to top