Grant proposal - Easy Contribution Guidelines for Rubicon Documentation

šŸ¤ Grants Program
1

Author(s) and contact info: Name: Dmitri Plotnikov Discord: !adsfasf#1629

About you: I am an experienced software solutions architect with a development background with 12+ years of experience in the IT industry.

Grant Description: The Rubicon documentation is a vital resource for users, developers, and anyone interested in the Rubicon DeFi ecosystem. However, contributing to the documentation can be challenging for newcomers, and it is sometimes unclear how to make changes or improvements. This grant proposal aims to make contributions to the Rubicon documentation more straightforward and accessible to everyone.

The Problem you hope to solve/study: Contributing to the Rubicon documentation can be intimidating and challenging for newcomers, and the lack of clear guidelines can lead to frustration and confusion. This can result in valuable contributions being overlooked or delayed, ultimately slowing down the development of the Rubicon DeFi ecosystem.

The Context of the Problem and helpful sources: Many open-source projects struggle with documentation, and Rubicon is no exception. However, by providing clear guidelines and links to relevant resources, we can make contributing to the Rubicon documentation more accessible to everyone.

The Criteria through which you evaluate the problem: The success of this grant will be measured by the number and quality of contributions to the Rubicon documentation. We will determine the success of this grant by monitoring the number of pull requests submitted and the overall quality of the contributions.

The Work you hope to do in response to the problem: The project will involve adding a link to the GitHub location of each page of the Rubicon documentation, providing clear contribution guidelines, and encouraging the use of GitHub issues for feedback and discussion. We will also develop a workflow to ensure that contributions are reviewed and accepted promptly.

The Reason for doing this work in response to the problem: By making it easier to contribute to the Rubicon documentation, we can encourage more people to get involved in developing the Rubicon DeFi ecosystem. This, in turn, will lead to a more vibrant and engaged community and accelerate the growth and adoption of the Rubicon.

Goals and Impact: This grant aims to make contributions to the Rubicon documentation more accessible and user-friendly. This will enable more people to get involved in developing the Rubicon DeFi ecosystem, resulting in a more engaged and vibrant community. The successful completion of this project will have several essential impacts that will benefit the entire Rubicon ecosystem.

Success will be measured by:

  1. The number of pull requests submitted
  2. The overall quality of the contributions
  3. The number of people who use the contribution guidelines and GitHub issues

Milestones: Assuming the grant is successful, the following milestones are proposed:
Milestone 1: Have a code update on the documentation site to automatically add a link to the GitHub location of each page of the Rubicon documentation ā€“ 7 business days
Milestone 2: Develop a workflow to ensure prompt review and acceptance of contributions. This includes cooperation with the Rubicon team to ensure that GitHub issues and Pull Requests are there and that there is a team to process user items. ā€“ 10 business days
Milestone 3: Develop clear contribution guidelines ā€“ 10 business days

Funding Request: 1700 OP

Budget Breakdown:
Development and implementation of a site functionality to automatically link to the GitHub location of each page of the Rubicon documentation - 800 OP
Development of workflow to ensure prompt review and acceptance of contributions - 450 OP
Development of clear contribution guidelines - 450 OP

Other Information: I look forward to contributing to the Rubicon ecosystem and helping to make it more accessible to developers and users alike.

I understand that I am responsible for reporting progress on this grant in the public forum. YES

1 Like
2

@hjksdfkjhsdfkhadfskh - Dmitri,

Thank you for taking the time to submit a proposal for improving the infrastructure of the Rubicon documentation. Reducing friction around contributing is a key component of encouraging organic growth in the community and an area the grants committee is looking to support. Considering the size of the requested grant, here are some additional considerations we believe could enhance your proposal and better align it with the ecosystem needs:

  1. Code-Update(s): Currently, there are several key items that must be addressed in the documentation repository / website. These include, but are not limited to:

    1. Link to the GitHub location of each page with clear contribution guidelines
    2. Support multi-lingual documentation with a widget (optionally store user preferences)
    3. Implement an auto-translation service to reduce manual overhead of translations
    4. Introduce a search feature to the documentation (ideally open-source)
    5. Update documentation to support user feedback, the Ethereum Foundation provides an example of this with both a widget and optional survey (ideally open-source)

  2. Documentation Workflow(s): Ideally, documentation should be managed through a continuous integration and continuous deployment pipeline that checks the state of the content before accepting new contributions. This process can include things such as:

    1. Defined templates for pull requests that eases the contribution process
    2. Linting to ensure style conformity throughout the codebase (ideally open-source)
    3. Automate testing for common mistakes (broken-links, spell checking, etc.)

  3. Accessibility: Rubicon strives to be accessible to all humans, and plans to be compliant with Web Content Accessibility Guidelines (WCAG) 2.1. Steps towards this goal include:

    1. Conduct an initial accessibility audit to determine necessary areas of improvement
    2. Ensure proper keyboard navigation so that the site can be accessed without the need of a mouse
    3. Implement a CI/CD process to help ensure that the site continues to remain compliant

This feedback is intended to help in iterating towards a finalized grant proposal that would receive grant funding. Please let me know if you have any questions regarding the feedback provided here or if we can be helpful in any other part of the proposal process. We look forward to reading any updates you make to your proposal and are excited to help you in your efforts to empower other Rubicon users.

denver - grants committee member

1 Like
3

Denver,

Thank you for your insightful feedback on my grant proposal for improving the Rubicon documentation. I understand the importance of addressing all the areas you mentioned, but I believe it would be more practical to focus on the Code-Update(s) section for now. This is because the project scope would be too large otherwise, and delivering on all the points might be time-consuming, given that the current site is based on the Markdoc template.

I have spent considerable time trying to deliver the five points you mentioned under the Code-Update(s) section but realized it might be better to find a different solution instead of reinventing the wheel. I came across the Nextra template, which offers many ready-made features to help address your points.

Here is my revised plan, focusing on the Code-Update(s) section:

  1. Prepare the Nextra template and make the necessary configurations to make it work
    0.1 Migrate existing content/pages
  2. Link to the GitHub location of each page
  3. Support multi-lingual documentation with a widget
  4. Implement an auto-translation service to reduce the manual overhead of translations (using a script with Google API integration to add pages when making a build automatically)
  5. Add a search feature to the documentation
  6. Update documentation to support user feedback with a link to GitHub issues in the report

Considering the time I have spent on proof of concepts, I have made significant progress. I estimate that I will need approximately one business day for each item on the list, totaling five business days. In light of this, I am requesting 1250 OP for the revised scope of the project.

I understand the importance of addressing Documentation Workflow(s) and Accessibility, and I agree that they should be delivered separately to maintain a manageable scope for this project. I look forward to potentially working on these aspects in future proposals.

Please let me know if you have any questions or need further clarification. I appreciate your support and the opportunity to contribute to the Rubicon ecosystem.

Best regards,
Dmitri

2 Likes
4

@!adsfasf#1629 - Dmitri,

Thank you for taking the time to revise your proposal in response to the feedback provided by the Grants Committee. We appreciate your willingness to adapt and focus on the Code-Update(s) section for this portion of the grant, as it is crucial to improving the accessibility and functionality of the Rubicon documentation. The Nextra template appears to be a promising solution with widespread adoption and support, weā€™re excited to see how it can enhance the Rubicon documentation.

The Grants Committee has reviewed your updated proposal and decided to accept it at the requested rate of 1250 OP. We believe that the proposed changes will significantly contribute to the Rubicon ecosystem by making the documentation more user-friendly and inclusive.

Upon successful completion of this project, the OP will be distributed as per the funding request. We will reach out to coordinate the payment upon completion through Discord. Throughout the project, we encourage you to share regular updates on your progress with the Grants Committee and the broader community.

Additionally, we would like to express our interest in potentially providing continued grant funding upon the successful completion of this portion of the grant. This would facilitate the completion of the ā€œDocumentation Workflow(s)ā€ and ā€œAccessibilityā€ portions of the feedback provided above, which are essential to further enhance the Rubicon ecosystem.

Thank you for your valuable contribution to the Rubicon ecosystem, and weā€™re excited to see your work come to fruition.

Best regards,

denver - Rubicon Grants Committee Member

5

@denver since the Code-Update(s) was already completed, letā€™s discuss the second one, Documentation Workflow(s).

Thank you for sharing your thoughts on the documentation workflow. I want to seek further clarification on the three action items you mentioned to understand better the results, limitations, and other aspects:

  1. Defined templates for pull requests:
  • Could you please provide more details on what elements youā€™d like to include in the pull request templates?
  • Are there any specific guidelines or best practices you would like contributors to follow while creating pull requests?
  1. Linting to ensure style conformity:
  1. Automate testing for common mistakes:
6

@hjksdfkjhsdfkhadfskh - Dmitri,

Congratulations on the excellent work youā€™ve done on the Code-Updates portion of this grant! Regarding Documentation Workflows and the questions youā€™ve mentioned above, Iā€™d like to share my initial thoughts with you.

Pull Request Templates:

  1. I would be more than happy to take the lead on this task, as most of the work involves defining the key elements of the template, as well as establishing best practices and guidelines for its use.
  2. If youā€™re interested in addressing this task within the scope of the grant, we are open to any suggestions you may have regarding the topic and its implementation.

Linting to Ensure Style Conformity:

  1. In the realm of open-source linting tools, Iā€™ve come across two notable options: markdownlint and Prettier. The primary trade-off between these tools is that markdownlint serves as a linting tool for catching errors, while Prettier automatically resolves any identified issues. Given the convenience of automation, I lean towards Prettier, but Iā€™d appreciate hearing your thoughts as well.
  2. When it comes to coding style guides, here is a comprehensive set of rules that we can use as a foundation for our style. Specifically, we should aim to comply with these linting rules: MD001, MD003, MD004, MD005, MD007 (modify default to 4 spaces), MD009, MD011, MD013 (unsure on this one), MD014, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD027, MD029, MD031, MD032, MD034, MD035, MD036, MD037, MD038, MD039, MD040, MD042, MD045, MD046(fenced), MD049, MD050

Automated Testing for Common Mistakes:

To address common mistakes, we can identify the sources of error and then implement solutions and automated testing to cover them.

  1. Broken Links & HTML Errors: Based on my research, html-proofer seems to be the most comprehensive and widely adopted automated tool for testing HTML files. Integrating the full range of checks that HTMLProofer can perform, as provided here, into a Github Action as part of the documentation CI/CD pipeline should address most HTML-related errors.
  2. Spelling and grammar errors: While Hunspell appears to be a solid spellchecking library, I think we should also try to cover grammatical errors in the documentation CI/CD pipeline. languagetool seems to be the most widely used and maintained repository for this purpose. As part of this process, we should allow users to update a shared config file containing specific text to be excluded as ā€œerrorsā€ because they are intentionally misspelled or do not conform to common grammar rules.
  3. Code snippet validation: Ensuring the accuracy and relevance of code snippets in documentation is crucial, as mistakes can confuse users and cause implementation issues. Iā€™m not certain about the best approach for validating code snippets across the documentation. There are several automated testing tools available, such as doctest for Python and markdown-doctest for TypeScript. However, setting up individual testing for each language referenced in the documentation may be cumbersome. A broader solution like embedmd could be an ideal long-term goal, but it would require a significant restructuring to a mono-repo format. I welcome any suggestions or ideas you have regarding this issue. Currently, I am against covering code validation in this grant.

In addition to automated tests, we should provide clear instructions to help users resolve any issues they encounter while contributing to the documentation. For example, we could explain how to modify the languagetool configuration file to allow for shorthand, non-grammatical sentences, and other intentional grammatical errors. Our goal should always be to decrease the friction of contributing to documentation, and any overhead that deters from that goal should be avoided.

Please feel free to reach out if you have more questions about the Documentation Workflows aspect of this project. I hope my input helps you finalize your grant proposal and establish project milestones.

best,
denver - Rubicon Grants Committee Member

7

@denver

I want to address some of the topics youā€™ve mentioned.

Pull Request Templates: I agree that defining key elements, best practices, and guidelines for Pull Request templates is essential. Since you are willing to take the lead on this task, I will focus on integrating the checks into the build script.

Linting and Style Conformity: I understand your preference for Prettier due to its automation capabilities. I am also inclined towards Prettier, and I will ensure that the chosen linting rules are enforced during the build process.

Automated Testing for Common Mistakes:

  1. Broken Links & HTML Errors: I agree that html-proofer is a comprehensive tool for testing HTML files, and I will integrate it into the build script.
  2. Spelling and grammar errors: Integrating Hunspell and languagetool seems like a good approach, and I will work on incorporating them into the build process. I will also ensure users can update the shared config file as needed.
  3. Code snippet validation: As you mentioned, setting up individual testing for each language in the documentation may be cumbersome. Since you are against covering code validation in this grant, I will not focus on this issue for now.

Regarding your question about fixing issues in the current codebase, yes, I will address any problems to ensure a clear build log. I understand your concern about warnings potentially being ignored by contributors. Therefore, I would like to seek your preference on whether we should generate an error or a warning when the build script encounters an issue based on the output from the libraries. An error would halt the build process and require immediate attention, while a warning would provide information about potential problems without stopping the build but may be overlooked by contributors.

Please let me know your thoughts on this matter and if you have any additional questions or concerns. I look forward to working on this project and improving the documentation process.

8

@hjksdfkjhsdfkhadfskh

Thank you for your response and update. You make an important distinction between errors and warnings during builds, I think at this point in time we should implement warnings instead of errors, this should decrease the barrier to contributing and allow for warnings to be evaluated on a case-by-case basis.

When it comes to spelling and grammar errors, I believe we can use just languagetool to solve this problem. Using Hunspell as well would most likely be redundant. Let me know if you have any concerns with this.

This is all that comes to mind at this time, I look forward to reading your completed proposal and milestones, please let me know if I can be of any further help in defining scope or goals for this portion of the project.

best,
denver - Grants Committee Member

9

Ok great. Let me work on a prototype, and Iā€™ll get back to you on Wed with milestones, etc.

1 Like
10

Denver,

Thank you for your input and suggestions. I agree that implementing warnings instead of errors would be more appropriate for our current goals, allowing us to evaluate contributions on a case-by-case basis while maintaining a welcoming environment for contributors.

I have devised a single milestone to cover the following tasks:

  1. Implement Broken Links & HTML Error checks with html-proofer.
  2. Ensure Style Conformity using markdownlint for markdown linting.
  3. Address Spelling and Grammar errors using languagetool.

After analyzing the available options, I have concluded that building these checkers as GitHub actions would be the most efficient approach. This way, we can accommodate tools written in different languages and simplify the process for contributors. They wonā€™t need to deploy the tools locally, and the core team can quickly review the output from the GitHub actions when evaluating a pull request.

I estimate that it will take me approximately 10 business days and 1750 OP to familiarize myself with these tools, fine-tune them, perform local testing, build GitHub actions, and fix any issues in the code based on the output from these checkers. Please note that this estimation assumes the tools are ready to implement. Any significant changes to the libraries would require a new analysis.

I hope this proposal meets your expectations. If you have any questions or need further clarification, please do not hesitate to reach out.

1 Like
11

@hjksdfkjhsdfkhadfskh - Dmitri,

The Grants Committee is excited to continue supporting your work on Rubiconā€™s documentation!

Given the widespread availability of existing open-sourced Github Actions for each of the tools addressed in your proposal, it seems unnecessary to build every Github Action from scratch. Examples:

  1. html-proofer: https://github.com/marketplace/actions/proof-html
  2. prettier: https://github.com/marketplace/actions/prettier-action
  3. languagetool: https://github.com/marketplace/actions/run-languagetool-with-reviewdog

Modifying these existing actions to ensure proper configuration to the repository should significantly reduce overhead in both the short and long term. Considering the current tooling and support for each of these services, the grants committee believes that an adjusted amount of 600 OP for this portion of the grant more accurately reflects the work to be done. In support of these implementations, any documentation needed for end userā€™s to diagnose or resolve errors encountered during the build is essential to the successful implemntation of this grant.

In regards to milestone #2: Ensure Style Conformity using markdownlint for markdown linting. - based on our previous discussions, we still believe using prettier is the better option due to its automated nature. While we might not follow every markdown style rule listed previously, the benefits of automation outweigh this loss of control.

We look forward to hearing from you and are excited to support your continued contributions to the ecosystem. Please let us know if you disagree with any of the feedback provided and we would be happy to discuss this further to find the optimal solution.

best,

denver - Grants Committee Member

12

Thank you for your feedback and continued support for my work on Rubiconā€™s documentation. Iā€™m glad you share my enthusiasm for improving the quality and usability of our projectā€™s documentation.

I appreciate your suggestions regarding using existing open-source Github Actions for the tools mentioned in my proposal. Iā€™m happy to help and agree that itā€™s okay to implement those tools, assuming they are fully functional. If I find any issues with these tools, such as critical malfunctions or unsatisfactory performance, or if they donā€™t meet our needs, weā€™ll have to re-evaluate the proposal and come up with alternatives. In such an unlikely scenario, please note that the time spent on this will have to be covered.

Regarding milestone #2, I understand your preference for using Prettier due to its automation. While we may not strictly adhere to every markdown style rule previously listed, I agree that the benefits of automation outweigh the loss of control in this case.

Once again, thank you for your support and valuable feedback. Iā€™m looking forward to implementing these changes and contributing to the growth of our ecosystem.

13

@hjksdfkjhsdfkhadfskh - Dmitri,

Thank you for your understanding and support when it comes to this portion of the documentation work, we look forward to updates on your progress. In the unlikely scenario that we need to modify the scope of the grant, we can reevaluate the proposal before further action is taken. Please let me know if we can be helpful towards your efforts in any other way, we appreciate your efforts to improve our ecosystem.

best,
denver - Grants Committee Member

14

Dear @denver

I hope this message finds you well. I wanted to share some updates with you regarding the lint feature that weā€™ve been discussing.

I have started working on the project and during the initial phase, I realized that ā€˜Prettierā€™ doesnā€™t support MDX. However, I managed to find an alternative. Thereā€™s a library created by the same team who developed MDX, which is available at GitHub - mdx-js/eslint-mdx: ESLint Parser/Plugin for MDX. Iā€™ve created a prototype using this library and, so far, it seems to be performing well.

I must note that this was not simply about using a ready-made action. The prototype required careful testing and integration. Due to commitments with my daytime job, progress has been a bit slower than initially anticipated, but rest assured, I am committed to delivering quality results.

The next steps for me are to finalize the lint feature, and then move on to the other two. As of now, my initial estimate for the lint feature stands at 325 OP. The estimates for the other two will be better calculated once I have a functioning prototype for the lint feature and have started exploring the others in more depth. There is some uncertainty regarding whether the ready-made actions will work with the MDX format, so I appreciate your understanding as I navigate this.

In light of these developments, I suggest we agree on the lint feature estimate as 325 OP. As for the other two features, Iā€™ll provide a more exact value after delivering the lint feature and starting work on the prototypes for the others.

Thank you for your patience and understanding. Iā€™m looking forward to getting back to you with more progress soon.

15

@hjksdfkjhsdfkhadfskh - Dmitri,

Thank you for the update on your progress and for the notice of the need to re-evaluate the grant before proceeding.

Itā€™s unfortunate that Prettier does not support mdx files. Thank you for finding an alternative solution that the documentation repository can utilize in the form of a Github Action. Given the need to build this individual action, the Grants Committee is happy to accept the proposed amount of 325 OP. I have gone ahead and created a repository for this work so that others may benefit from this tooling, you can find it here. If you would submit your work, along with supporting documentation, on this eslint-mdx Github Action as a pull request to this repository, that would be greatly appreciated.

In regards to the other two features, html-proofer and languagetool it seems like the best path forward would be to simply implement html-proofer and disregard languagetool to avoid any unexpected mdx conflicts. In line with the original proposal, a rate of 200 OP feels appropriate for this feature.

Please let me know if you have any questions or concerns, or if we can be of any further help in this process.

best,
denver - Grants Committee Member