Documentation currently is very technical and is catered to a very small audience - those who understand the math behind it as well as solidity + underlying ethereum architecture. The idea of this documentation overhaul is to generate content and promote easy access to it such that the friction of understanding balancer and contributing it is reduced
The Problem
Given documentation is so highly technical we are excluding the majority of users who may want to understand and learn more:
Potential LPs who want to understand high level how it works, what the risks are and what the benefits are for providing liquidity to balancer
Potential traders who want to understand how to trade using balancer and why they should use it over a CEX
Potential developers who may want to build applications and extend functionality of Balancer. The key point I would put here is that there is a large group of very talented developers who may not understand the technicalities but if it was abstracted and made easier would potentially be able to contribute a lot. If we look across the crypto ecosystem we can see this clearly where UX and design are lacking when compared to Web2.0
Proposed Solution
We believe that there are a couple of key factors to solving this problem:
FAQ documentation: there are many questions that come up in support many times. We need well documented FAQs that are able to be updated easily
Long form LP documentation: this should be high level understanding of what the pool is, what the risks are, what the benefits are etc.
– It should also include how to guides
Long form trading documentation
– How to use the exchange
– Pros/cons of DEX vs CEX
Information Architecture revamp: we need to update balancer.finance layout such that information can easily be found. Some examples of this are:
– On the exchange + pool sites adding links to relevant documentation
– Updating balancer.finance to include built in FAQ pages and highlighting these
– Updating balance.finance navigation and grouping concepts to relevant users (e.g. developers tab for dev related topics, info tab for general public, etc)
[Nice to have]: a community showcase section: tools such as pools.vision can be linked here providing they link back to balancer.finance. This is great for a couple of reasons:
– We are able to showcase and point users to extremely useful tools that the core team are otherwise unable to build
– SEO gives us nice backlinks
– Shows the developer community our support for them + gives them a platform to expose their work
Proposed Milestones
FAQ documentation written and published on the main site (NOT docs.balancer.finance)
Update the information architecture of balancer.finance
Updating content for regular traders
Updating content for LPs
Community showcase
Other Details
I think that this should fall under the already approved marketing/growth proposal under Phase 2. I did promise Fabien to create a new proposal where there are discrete pieces of work that are clearly deliverable so have put together this one.
Depending on which elements of work we’d like to do I would guesstimate that it would be fair anywhere from 3K - 5K BAL tokens
I think we should price grant in USD and not with BAL because the price may not make sense in 1 week or 1 month. TBH i through the grant you were asking in your first proposal include the phase 2. Do i understand this right that you would need 3 to 5K BAL (around 60K$ to 110K$ at this time) to delivery phase 2? How long would it take to deliver can you commit to some date or duration for the milestones?
Happy to price in USDC: yes it is around 60k - 110k depending on the work required.
I don’t think I will commit to dates for the time being as I still think that the analytics piece should come first and so I would prioritise work on that over this one. But if we are talking duration then what I am thinking with respect to the milestones:
FAQ documentation written and published on the main site (NOT docs.balancer.finance)
– 2-4 weeks, we should aim for 3-4 iterations before live
Update the information architecture of balancer.finance
– 1-2 months. I think this can actually be delivered in phases, ideally we should be able to test and see if the IA actually improves
Updating content for regular traders
– Same as (1)
Updating content for LPs
– 4-6 weeks, this one seems to have the most amount of questions right now so we should aim to roll out and then keep adding more
Community showcase
– Probably needs more discussion about how we do this. Actual build lets assume 4-6 weeks, process to listing it is where we need more discussion
Just to note I don’t believe that 1-5 is in sequential order. Most of these things can be done in parallel and just depends on how many people we want to bring on board. From the content side I think the biggest thing is going to be standardising the tone of voice such that it makes sense and is consistent across everything.
All up I think this project would take ~3 months to deliver end to end, with deliverables being able to be delivered as early as 2-3 weeks in.
I’m more than happy to work on putting this together while you’re doing the analytics piece, tongnk. I definitely think it would be useful to continue to have other users periodically help refine what I’m putting together. Maybe @solarcurve and @rabmarut could be useful viewpoints as well to check out some of the documentation. It might also be useful to find some reliable non-experts to use as guinea pigs for some of the high level overview docs.
Yep I think there’s a lot of content that needs to be written up - potentially if you have an idea of maybe the topics to see if we line up in thinking?
The biggest piece of work though is going to be restructuring the site such that everything flows together and the correct information is highlighted. Given previous experience this requires a lot more thought than one assumes on the outset.
One of the largest considerations that I would love input on is whether we want to do a redesign and migrate the site away from Wordpress. It’ll mean a lot more control over the user experience and the flow of information without hampering us in the future
Why not improving the documentation at docs.balancer.finance? I think it’s better if there is a single place for documentation and not spread on multiple sites. Also i believe if you really want 60 to 110K$ for this grant you will need to provide much more details on what you going to do. Maybe make a proposal for each of the points.
I think that currently the fact we have all of the documentation on docs.balancer.finance doesn’t really work. I would propose a couple of things:
docs.balancer.finance becomes developer documentation - this is standard behaviour that developers are used to. It’s normally stand alone documentation where people don’t navigate back to the main site which is fine
We build out LP and trading documentation into the actual balance.finance site
As part of this I am proposing we consider rebuilding the main website entirely in something other than wordpress. This will give us more control to then embed FAQs and long form documentation in places which makes sense to the user.
– As an example of what major rebrand the team has worked on is here: lumi.com.au - it has been optimised over hundreds of experiments where we saw conversions increasing from ~9% to well over 30% now (whilst having increasing volumes which for anyone who has done this before, knows it is a damn hard thing to do). This can be replicated on Balancer!
– SEO updates: we will want to move balancer.exchange -> balancer.finance/exchange OR exchange.balancer.finance. Same with pools.balancer.exchange. Or we move it all to balancer.exchange, either or we need to consolidate
It’s one thing to write content but if nobody reads it like right now then it doesn’t matter how good content is. My guess is right now people go on website, find documentation too complex or can’t find what they are after and go to discord to ask very basic questions
I based the majority of the estimates on the rebuild component with designs. If we were to simply rewrite content I believe we can do this with 10-15k.
I wouldn’t make this into two separate proposals given my above points. I am happy to have it delivered in tranches where it is only released on milestones and we are happy with said milestones.
If you have a read of the post just before it’s actually quite a lot of work - I am proposing a redesign + rebuild in addition to the content. In addition there is most likely going to be ongoing maintenance that is required as we tweak and add documentation.
Additionally in order to actually build out good documentation I am basically acting like tech support and on the discord nearly every hour I am awake (even when I am at work) to understand user frustrations and questions.
Add all of this work with the fact that tokens are locked for a year (i.e. we don’t see a cent of this for the work we do now) AND the token value may reduce (given inflationary nature of token with the rewards issued currently) I actually believe it’s fair.
For those in industry who consult this is actually very low…
Dont you have another job as well? Are your employers cool with picking up more work>
I am sure others are making more in the industry but I dont think you have the competence or the experience to do this. You are just trying to rip off people around here.
Just posting after some further discussions with @fabien so that everyone is on the same page:
Current belief after discussion is that the key to this project is going to be around the actual delivery of the content to the user rather than the actual content itself (though this is still very important).
Proposal is similar to an intercom/matcha where we structure it as follows:
Developer docs: stays the same at docs.balancer.finance. We will probably want to update language here to move away from math to more technical
LP + trader docs: we should move this into the main site and section it out
FAQs: this should live in it’s own section and we clearly highlight it out
Development, redesign and moving away from Wordpress will allow for some very strong SEO benefits (tie in exchange and pool all into balancer.finance) as well as better control for information dissemination.
Lastly Fabien suggested that we finish off the initial grant regarding analytics and insights before we continue on this. So I think any further discussion on this topic here might be more useful to discuss if we want to do a big piece of work on rebrand + migrate off WP as it’s a big piece of work.
Hey folks, thought it’d be useful to set some comparative context here.
The Algorand FAQ (public on Reddit) took about 3 weeks, from start to finish, costing less than USD $5k in the end. It took is the work of 3 people: an Editor who outlined and produced revisions of the project; an Algorand community member who collected sources per the Editor’s questions, from which the Writer can synthesize responses; and a crypto-savvy Writer who produced the work for an affordable per-word cost.
While not a 1:1 comparison, it’s hopefully useful to know what a fairly substantive, public-facing document for a major protocol cost to produce, in order to reverse engineer the expected spend for this project.
100%. I’ve been telling everyone that the content is NOT the expensive part.
You can write content til the cows come home but if you don’t build it such that it exposes to users correctly then there is literally no point. If you imagine someone who structures documentation all in one (as most projects do) and if you then try to search for something (say imp loss) you may get a technical mathematical formula which is good for some, but for the majority it’s absolutely useless.
In my opinion, without good delivery there is no point of simply writing content for contents sake.
I think this grant is way to much for what it is looking to do. I think its a great idea to have better documentation and information, but the requested amount is no where near what it would cost your looking at tops 30-40k and that’s pushing it also a lot. Great idea and love it but asking way to much.