Funding Proposal - Subgraph Documentation

Proposal Information

Proposal description:
Work request for this project was submitted to the Graph Advocates DAO by 1Hive. This proposal funds the working hours it take to complete subgraph documentation for total of 5 subgraphs:

  • Aragon Connect
  • Aragon Agreement
  • Celeste
  • Gardens
  • Honeyswap

Link to actual docs - Subgraphs - 1Hive

Vote to fund proposal here

Project Title: Documenting Subgraphs with the Graph Protocol for Improved Transparency and Query Development

Project Overview:

We completed subgraphs documentation to improve transparency, accountability, and query development in data analysis. Subgraphs are often used to analyze specific patterns or relationships within the data. However, documenting subgraphs is often overlooked, leading to difficulty in interpreting and communicating the findings.

The proposed project aims to address this gap by creating a framework to document subgraphs using the Graph Protocol, an open-source decentralized protocol for indexing and querying data from blockchain networks. The project will involve the following activities:

  1. Development of a documentation framework: We will develop a documentation framework that covers important information about your subgraphs, includes links, detailed description of your entities, and query examples.
  2. Implementation of the framework: We will implement the documentation framework and help get the documentation uploaded to your Gitbook for internal and external developers to review as they use your subgraphs.
  3. Query development: By documenting subgraphs with the Graph Protocol, we can develop more complex and meaningful queries. The documentation will provide the necessary information for researchers to build queries that can answer specific research questions and generate insights from the data.

Conclusion:

By documenting subgraphs with the Graph Protocol, we can improve transparency, accountability, and query development in data analysis, leading to better decision-making and improved trust in the blockchain industry. We believe that this project will contribute to the better understanding and use of your project’s subgraphs.

Team Information (For Funding Proposals)

Paul - Discord PaulieB#0047- Technical Writer

Chidubem - Discord Chidubem#2408 - Technical Writer

Skills and previous experience in related or similar work:
We have worked together and individually on over 20 projects subgraph docs including such projects as: ENS, Sablier, DAOHouse, Polygon and further examples can be provided upon request.

Funding Information (For Funding Proposals)

Amount of HNY requested: 130 HNY (~$1,600 at current price) - Revised to 66 HNY ($800 at current price) see below.

Ethereum address where funds shall be transferred: 0x384C460A8bF7D15B48cB062d938E410860647Ef7

More detailed description of how funds will be handled and used:

The funds will be used as payment for work completed do document the five subgraphs the project utilizes with the graph

This proposal pays for 2 Technical Writers working a rate of 4-5 hours on each subgraph for a total of 20-25 hours

1 Like

While I appreciate the effort and importance of documenting subgraphs for improved transparency and query development, it’s difficult for me to support this funding proposal for the following reasons:

  1. Cost per hour: The requested pay rate of $64-$80 per hour appears to be on the higher side, especially when taking into account the available funds within 1Hive. Furthermore, many of us who work here do not receive rates close to the proposed rate.
  2. Priority: This service could potentially increase GRT consumption, which would again affect 1Hive’s funding. I believe we should prioritize funding for projects that provide clear value. I could be mistaken on this point, but it’s how I currently see the priorities within 1Hive.
  3. Misunderstanding about team affiliation: I initially assumed that you were part of TheGraph’s team. If I had known beforehand that this would be a separate service, I would have raised the same concerns mentioned here.

Note: I understand that the documentation has already been completed, but access to the GitBook is restricted, preventing the community from evaluating the quality and relevance of the work. Additionally, there is insufficient proof of past experience, as the proposal does not provide specific examples or links to previous work.

This is only my personal opinion, and it reflects how I perceive the current priorities within 1Hive. Please feel free to discuss further if you have alternative perspectives or suggestions.

4 Likes

Thank you for considering our proposal. I want to clarify that the subgraph documentation request was not solicited but rather submitted by 1Hive through the Graph Advocates DAO subgraph docs request process, not directly to The Graph. I apologize for any confusion on this matter.

Subgraph documentation provides significant value by clearly explaining the purpose and functionality of the subgraph. It also makes the subgraph easier to use and maintain, facilitates collaboration among developers, and builds a community around the subgraph. Well-written documentation can ensure the subgraph’s longevity by providing information on its design and dependencies, and by making it more accessible and understandable to developers interested in using or contributing to it.

Regarding the cost of subgraph documentation, I’d like to clarify that the standard price for this service is typically $350 per subgraph. However, due to the submission of five requests, we were able to use a lower rate of $320 per subgraph due to the complexity and research it takes to review each protocol. Before commencing the task, we discussed pricing through Discord with a team member and agreed that $1,600 was a feasible amount. However, we would require a funding proposal, and it is possible that 50% of the payment would be made in locked HNY tokens. If this is not feasible, we are open to exploring other options that work for both parties.

On the funding submission form, I was only able to include two links. For previous work completed, you can find examples in this article (Subgraph Documentation — How to document your subgraph using the Graph Advocates | by paulieb.eth | Medium).

Thank you for your time and consideration, and please let us know if you need any further information. I can provide links to our Github pull request (below) to view the work. The team should be able to view the docs on the link on the initial proposal. The forum only allows me to enter two links in each forum entry.

1 Like

Hey - I submitted the Subgraph Doc Request for this and have been talking with @Paulieb since then. When he told me what they typically charge for the work I let him know about 1Hive funding proposals and suggested going that route.

I agree that $1,600 is steep given 1Hive’s financial situation. Originally I suggested asking for time-locked or streaming funding. After talking with Paulie today it sounds like they’d prefer to either lower the amount of this funding proposal or wait to see if the Quests funding proposal passes since this might be a good use of Quests bounty funds (though at a lower amount).

Paulie’s team did great work with the documentation (which is in the wiki here) - and I do think they should get some compensation for this.

@Paulieb can you clarify your team’s relationship with The Graph? Do they not compensate any of your work on this documentation?

1 Like

Hey Paul, thanks for the clarification; I also like the idea of the Quest thing (in a non-objective way :stuck_out_tongue: ) Just to mention that the here link point to the forum proposal not the wiki

Paul - I am member of Graph Advocates DAO and so is the co-author of the docs Chidubem. The Graph Advocates DAO was established by the Graph but runs independently - The Graph Advocates Program Has Launched to Grow the Community of Web3 Contributors - The Graph Blog

Would $800 or $160 per subgraph be an amount that would work? This is 50% of initial ask The DAO supports advocates creating documentation for projects since there are synergies, but not something they pay since work is primarily beneficial to the project. We can attempt to ask them to supplement some of the work payment in this case to offset. Previously, we have only done mostly 1 subgraph for projects and few multisubgraph projects. Please let me know if this works. Here is link to Wiki which the work is posted. Hopefully is can be viewed - Here - Honeyswap - 1Hive

$800 sounds reasonable to me :+1:

Thanks for giving some more context on Advocates DAO

1 Like

fixed thanks Gossman!

1 Like

Hey Team! I revised the funding proposal to lower amount $800 or 66 HNY - Vote to fund proposal here

That its still unable to access, maybe its some confinguration to allow be public

That for all 5 itens there.

image

Also its not clear to me what is the Aragon subgraph. Do have some idea @Gossman123 ?

Ah on that i can view, so the problem its the links in the first one, our side?

I don’t know either :S

Ahhh yep my bad - I just fixed it try again: Subgraphs - 1Hive

Hey @kamikazebr! The subgraph provides an API that developers can use to retrieve various data points related to the Aragon DAO, including information about the DAO’s members, voting records, proposals, and more. Developers can use this data to build their own applications, such as dashboards or analytics tools, on top of the Aragon platform.

I can throw in a sweetener to help process this if I may. I agree to add descriptions we used in our documentation to you Schema on all 5 subgraphs. Example - honeyswap-subgraph/schema.graphql at main · 1Hive/honeyswap-subgraph · GitHub. Currently they are not all filled out. @paul @Gossman123

I have completed 5 of 5 pull requests to add the descriptions to the Schema. This is adding several more hours to the job and more value to your project. Now descriptions will populate in the playground and on websites when you hover over each entity to help anyone working on queries.

Screenshot 2023-04-04 at 11.03.59 PM

Adding descriptions to your schema on graph subgraphs is important for several reasons:

  1. Enhance understanding: Descriptions help users understand the purpose and contents of a subgraph. A clear and concise description provides context and clarity, making it easier for users to comprehend and navigate the schema.
  2. Improve documentation: Descriptions act as documentation, providing valuable information about the subgraph that can be used by developers, analysts, and other stakeholders. Documentation helps ensure that everyone has a shared understanding of the subgraph and its contents.
  3. Facilitate integration: Descriptions can be used to help integrate the subgraph with other systems or tools. A clear and concise description can help developers understand how to use the subgraph and incorporate it into their own systems.
  4. Enable discoverability: Descriptions can be used by search engines and other tools to help users discover relevant subgraphs. Including descriptive information in your schema can improve the chances that your subgraph will be discovered and used by others.

Overall, adding descriptions to your schema on graph subgraphs can improve the usability, maintainability, and discoverability of your schema, making it a valuable practice for any schema author.

I like the fact that its integrated in the Subgraph app.

1 Like

This funding has been moved to Quest funding FYI

1 Like