Maintain Ocean Protocol core component documentation

OceanDAO Round 10
#1

Part 1 - Proposal Submission

  • Name of project: Maintain Ocean Protocol core component documentation.

  • The proposal in one sentence:
    As Ocean core components that power the ocean economy are constantly evolving, I propose to maintain the documentation for a period of 3 months.

  • Description

  • Grant Deliverables:

  • Create and improve v4 docs

  • Create and improve tutorials

  • Regular maintenance of docs website: https://docs.oceanprotocol.com/

  • Which category best describes your project?.

    • Build / improve core Ocean software

  • Which Fundamental Metric best describes your project?

    • Other: Help improve Ocean Protocol adoption by maintaining documentation

  • What is the final product?:

Regularly updated docs and improvements in https://docs.oceanprotocol.com/. The exact task tasks, issues will be discussed with the Core team and can be tracked on github.

  • How does this project drive value to the ā€œfundamental metricā€ and the overall Ocean ecosystem?
    • ROI
      • BANG
        • The project will save the time of the developers who use Ocean Protocolā€™s technology. Assuming that better documentation will save 20% of the time spent on getting started, troubleshooting, going through updates, in a week a full time developer working 40 hrs weekly will be able to save 8 hrs/week. So, in a month savings will be 4 * 8 * 30 (hourly pay in $) = $960/developer. And, in a month 10 developers are benefited so, value = $9600/month.
        • Good quality documentation will increase the outreach in the community and attract more developers and thus foster growth of the Ocean Ecosystem. Assuming that due to better documentation, 2 new developers/month start using Ocean Protocolā€™s technology and each developer generates a value of $2500/month. So, total value generated is 2 * 2500= $5000/month
        • Based on the above arguments, value generated = 9600 + 5000 = $14600/month. So, value generated for 3 months = 43800 Ocean tokens
      • BUCK
        • The $8000 grants will be used to maintain the documentation for 3 months.
      • CHANCE OF SUCCESS
        • I determine the chance of success to achieve the desired outcome is high based on the fact that I have previously worked with Ocean Protocolā€™s technology stack.
        • I have completed the planned tasks with the help of the Core team in the previous grant rounds.
        • To put in numbers, 90%, though I would aim to complete the work with 100% completion status. I am leaving 10% as a chance of failure because of any unforeseen circumstances that might cause the delay in the delivery of the work.
      • FINAL ROI RATIO
        • BANG/BUCK = 43800/8000 = 5.475
        • 5.475* 90% (CHANCE OF SUCCESS) = 4.9
  • Funding Amount: $8000
  • Have you previously received an OceanDAO Grant?

Yes, I had received the OceanDAO Grant in Round 2 and Round 7.

Part 2 - Team

Core Team

Akshay

  • Role: developer
  • Relevant Credentials:
  • Background/Experience:
    • Successfully completed 2 Grant proposals for documentation maintenance.
    • Worked as a backend developer in trading applications at CLSA from July 2018 to Jan 2021.
    • Completed Bachelorā€™s degree in Computer Engineering from Pune Institute of Computer Technology, Pune in the year 2018.
    • I have knowledge and hands-on experience in Java, Reactjs, nodejs, python, NoSQL/SQL databases.

Part 3 - Proposal Details

Project Overview

What problem is your project solving?

Ocean core components that power the ocean economy are constantly evolving. But, the documentation related to the changes in the Ocean tech stack is not maintained at the same pace. This creates a hurdle for the developers who want to develop applications using Ocean Protocolā€™s technology.

Documentation is a very crucial part of any cutting-edge tech like Ocean Protocol. Documentation is the entry point for all the developers willing to contribute to the new technology. Ill-maintained docs cause more frequent developer churn. A well maintained and up-to-date documentation will help to save developersā€™ time and bring in more devs and dapps on Ocean Protocol.

For the upcoming releases of core Ocean Protocol components, I aim to develop the documentation. For the upcoming V4, I will work together with Core team members for the development and maintenance of the documentation.

E.g. https://github.com/oceanprotocol/multi-repo-issue/issues/93

Thus, I propose to regularly maintain all the README.md files, setup guides, doc strings in the source code, and release the changes to https://docs.oceanprotocol.com/.

What is the final product (e.g. App, URL, Medium, etc)?

  • All the documentation of the Ocean protocol projects will be up-to-date for upcoming releases.
  • Regular maintenance and improvement of the existing doc website.
  • Github repositories showcasing the use of Ocean libraries.
  • Continuous maintenance of documentation of all the Ocean core components.

Grant Deliverables

  • I would keep track of updates and changes in the following projects under Ocean Protocol on Github and update the docs
  • I will work with Ocean Protocolā€™s core team to keep the documentation updated and help new developers with solving technical issues related to environment setup and library use.
  • The official Ocean protocol documentation website will maintained and updated regularly:

Project Deliverables - Roadmap

Additional Information

  • Involvement with Ocean Protocol community so far:
    • Built PayFait under Data Economy Challenge (1st edition) and won the prize as well.
    • Completed the project datapolis.net under Ocean v3 program.
    • Involved in the Ocean Ambassador Program.
    • Working as a developer for Dataunion.app which is funded by Ocean Protocol under the Shipyard program.
    • This project has already completed 2 grant proposals.
2 Likes
#2

I wholeheartedly support this proposal. Iā€™ve worked closely with Akshay in helping guide him on what documentation to work on, and he consistently delivers with high quality. The results at docs.oceanprotocol.com speak for themselves. Iā€™m looking forward to seeing Akshay continue his great work:)

5 Likes
#3

Hello there!

Is it possible to add documentation regarding Aquarius and its changes over time? That would be awesome.

1 Like
#4

For me, that would have been a great addition too. But additionally, Iā€™d like to stress the fact that what should be documented is not arbitrary but potentially useful information. Currently and in the past, I believe a lot of supposed-to-be information has been neglected to be documented. Having documentation run as a parallel task to development might be making this issue worse. Good documentation scales a software productā€™s usage and development. Bad documentation increases communication overhead.

Aquarius is a great example of this. Actually, a lot of work and decision-making has been put into its software, but along the way, all of this information has gone missing as no one ever wrote it down during the process (at least not so that I can look at it online). Iā€™ve been developing for 9 months with the Ocean Protocol now, and I hardly ever look at its doc page to do anything as mostly I canā€™t find relevant information there.

Donā€™t get me wrong: Thereā€™s information, but itā€™s the kind of information that is classical for documentation being developed on the side. It fits the repository and code, but itā€™s really not helpful or allows one to gain additional insights.

If you visit this website: https://docs.oceanprotocol.com/references/aquarius/, sure: All routes of Aquarius are listed: But it remains impossible to understand how to actually use Aquarius in real life. The public endpoints arenā€™t listed. The docs arenā€™t versioned; the changelog isnā€™t linked. Requests and response bodies arenā€™t included and for the query endpoint, it is implicitly assumed that an external user is capable of inferring that the elastic search query language is in parts used.

Iā€™m supporting this proposal in the hope that conceptual changes to the Ocean documentation are made such that developing becomes possible for external projects.

1 Like
#5

hi @TimDaub, @realdatawhale ,

Thank you for your thoughts on possible improvement areas for docs. We will address the pain points as soon as possible.

We already have a Pull request ready to be merged for displaying Aquarius api responses in docs:

We will also add documentation for request body and more usage examples.

Please feel free to post here or create issues in docs repository for more specific documentation requests.

2 Likes
#6

awesome, thatā€™s great!

#7

Superb. Looking forward.

#8

Hey CleanDocs,

We just submitted our vote for this proposal and good luck! Our devs also have worked on an Aquarius documentation that might help you kick off the work for that library!

If you have time, go ahead and review our Proposal on the Port. Let us know whether you have any comments.

Cheers,
Data Whale

1 Like
#9

Hi Akshay, I just wanted to reply to your proposal, provide my support, and say thank you for all of your contributions towards helping to improve core Ocean documentation!

Itā€™s incredible to have your participation in the community, and I honor your commitment to remain a ROI>1 project.

1 Like
#10

Hi Akshay,

Hereā€™s a short document our devs created on how to query Oceanā€™s subgraph successfully for pool assets. Itā€™s short, but sweet. It took us quite some time to make this work, due to missing documentation. Therefore, I do believe your work holds value for external teams that are navigating the Ocean Git to build third party applications!

Cheers,
Data Whale

1 Like
#11

Thank you for sharing the document! We can add these queries as use cases for subgraph to help external developers build their own queries.

#12

Deliverables from our last proposal (what we achieved) :
[X] V4 documentation: Released documentation: docs.oceanprotocol.com PR(V4 by akshay-ap Ā· Pull Request #936 Ā· oceanprotocol/docs Ā· GitHub)

#13

I would like to use this wallet address henceforth: 0x169821D39aEBE75E6E6550d03Eb0B2eec3AF991a
@idiom-bytes can you please look into this.

1 Like
#14

Hi @akshay, can you please try again? Thank you!

#15

Project submitted deliverables:

1 Like
#16

Admin:

Hi @akshay,

Thank you for submitting an update for your previous proposal! I am a Project-Guiding Member and have assigned myself to help you.

Your Grant Deliverables have been reviewed and look to be in good condition. You are ready to apply for another grant.

All the best!