Improving the UX for docs

[prjctimg]

A lot of effort needs to be put into improving the overall UX of the documentation site.

Over the next month we'll be adding small but noticeable improvements to help make it easier to navigate the site. Contributions are greatly appreciated devs!!

[prjctimg]

Any suggestions @adarshswaminath ?

[adarshswaminath]

That sounds like a fantastic initiative! Improving the UX of the documentation site is crucial for providing a better user experience. I'd love to contribute and help make these improvements. Could you please share more details about the specific areas you're planning to work on or any particular tasks that need attention? This way, I can jump in and start working on the areas where my skills can be most beneficial. Let's collaborate to enhance the site's usability and accessibility!

[prjctimg]

Great! The optimism and energy will push us beyond 👽!

I've added some things I think need attention at the moment and still updating the list. The documentation site uses Nextjs and TailwindCSS. You can go to timlrx and click on the "nextjs-starter-template" to familiarise with how it works.

Of course, if you have simpler alternative, please share with us so that we work smart not hard!

[prjctimg]

@adarshswaminath

The entire documentation site needs touch ups here and there so I have tried to split up the tasks into parts Homepage, Reading View, and the ListView.

The palette could be changed to one with cooler colors like blue and the components could use a bit more border radius to give a relaxed feel.

I'll break down the tasks over the following comments

[prjctimg]

Homepage

People like what they see so a pretty landing page is a necessary aesthetic. I think they're plenty of landing page examples out there for libraries but here's what I had in mind:

• A flowfield coverpage that has shifting colors (kinda makes the project goal obvious that its about color). This could be preferably full viewport.
• A description of the library capabilities, a getting started section and at the footer we can put some statistics about the project e.g stargazers, forks and contributors.

I've attached an example landing page above. Feel free to make suggestions

[adarshswaminath]

@prjctimg @H-K-R @foss2cyber @takanome-dev I've created another pull request in the docs. If it's messy, I apologize—I'm new to being a collaborator

[takanome-dev]

There's an issue for this enhancement, right?

Oh yeah but no worries 😅 @adarshswaminath can you let @foss2cyber work on the hero section? He seems to be interested. I assigned him the issue #70

And to avoid conflicts and ensure a smooth collaboration, we may need to have clear processes and guidelines in place for our dev team and contributors like a CONTRIBUTING guide.
But for now, before start working on a feature or bug fixes, let's first open an issue and assign ourself (or a contributor). Then, mention in our pull request what issue it fixes.

@prjctimg feel free to create templates for issues and pull request.
Learn more about templates:

• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates
• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository

Examples:

• https://github.com/takanome-dev/blog-with-astro-golang/blob/main/.github/PULL_REQUEST_TEMPLATE.md
• https://github.com/takanome-dev/blog-with-astro-golang/blob/main/.github/ISSUE_TEMPLATE/bug.yml

[prjctimg]

@takanome-dev Woah 🤯

This sounds like an optimum workflow. Is there a way we can automate some of these tasks as well ? Such as GitHub Actions?

Will definitely check out the articles enlisted soon!

Currently working on a major pull request for issue #68

A lot of testing is coming 👀

[takanome-dev]

Is there a way we can automate some of these tasks as well ? Such as GitHub Actions?

Yeah we can automate assigning issues with github actions, like we do on open-sauced. i.e -> open-sauced/app#1988

Here is the workflow file -> https://github.com/open-sauced/hot/blob/beta/.github/workflows/triage.yml

[prjctimg]

Is there a way we can automate some of these tasks as well ? Such as GitHub Actions?

Yeah we can automate assigning issues with github actions, like we do on open-sauced. i.e -> open-sauced/app#1988

Here is the workflow file -> https://github.com/open-sauced/hot/blob/beta/.github/workflows/triage.yml

Okay, thanks! Will customize it a bit to suit our variables. Will also check their CONTRIBUTING file and see how they did it.

Currently working on ESLint, Prettier and husky config.

[prjctimg]

ReadingView

For the reading view, there a few adjustments that could be made to make the documentation easier to read and navigate.

• A reading progress bar that updates as a user scrolls down the document here is an example blog post on such a feature

• A Table of Contents Table that lists all the headings in the document. Since the source files for the docs are plain text files .mdx we could use a remark-plugin or a RegExp that maps through all headings and adds them to the TOC

• The code blocks scroll horizontally on small screens. It would be nice to add some wrapping add use a lighter monospace font for the code blocks (I think the font for code is a bit too heavy)

• An edit in GitHub button on every page so that its easy to fix typos and adjust the docs. A 'was this doc' useful statistic would also help us better our documentation, but of course its a 'nice to have' feature.
  

• Add a link to the source code for each utility. Since every H4 element in the doc source files is a heading for a utility we can attach these links by dynamically attaching the heading title to a path pattern to the repository

As you can see above, source and npm package are links that lead to external resources. In this case we only need to link to the source. Also notice how the details for each component are laid out in a well spaced manner making readability a breeze. All the utilities are documented using a uniform schema containing the fields:

• Parameters
• Description
• Returns
• Example

Maybe a React component to template this layout would be effecient.

[prjctimg]

ListView

For the list view, there's not much to change except make a few design changes to the basic unit (each post in this case). The list would look more engaging if it had shadows and had each post in card format. Here's an example of what the card could look like. I have taken it from George Francis's personal blog