1hive Wiki Proposal

🌿 Proposals
#1

1hive Wiki Proposal

Proposal Information

Background:

With the increasing demand for quality control around documentation (see rationale) we are proposing the Fauna Swarm take primary responsibility for documentation oversight to be within their scope of work. This documentation will be stored on an independent wiki repository on the 1hive github. Fauna was initially formed to providing support and/or act as moderators. Terra is dedicated to translating 1hive projects, documentation and resources and will support Fauna in with quality control for translations. This does not mean Fauna will be the creators of the documentation. Anyone will be able to help standardize and consolidate documentation (wiki).

The topic of developing a wiki started well before I become a member of the 1hive. However, after reaching out to the 1hive community several pointed me in the direction of Luigy lemon. I began my conversations with Luigy lemon in late October. Over the past month I have had about a dozen very intentional meetings including over a dozen 1hive members via live voice chat, discourse, and discord. The primary contributors that have been very helpful in this pursuit have been lEscanore & luigy đ—čđ—Čđ—șđ—Œđ—», thank you. If you wish to know others who contributed, I can provide their names if community wishes.

Proposal Rationale

At some point when a new user joins the 1hive or tries to access the faucet they start to look for answers that start out basic. The questions are mostly geared towards interacting with the different interfaces such as the bridge, metamask, honeyswap, the faucet, getting verified, the farm, etc. At some point in their journey at the 1hive they may come across pollen and find out that contributing to the 1hive can earn you cred. As they look to see how they can help, they quickly come across dozens of articles and videos. A lot of the articles end up providing similar information just being presented in a different way and occasionally some new information too. After hours of reading and watching videos the new user may have read 5 different articles all stating something similar. Such as, about new users, faq, or getting started [1][2][3][4][5][6] but after reading they walk away feeling they invested a lot of time but in return the material didn’t fully answer the questions they were seeking. Some will ask the discord, some will just leave because they couldn’t understand how swarms worked, and maybe some make another attempt going through 5-10 more articles and even possibly re-reading the same article they’ve already read once before. A structured wiki with a quality control process is being proposed to help consolidate a consistent message. This will help new members and the 1hive community to quickly and easily find the answers to the questions they are seeking.

[1]What are Swarms? 1hive explained - :honeybee: Community / Learning - 1Hive
[2]Everything about 1Hive in one place - newFAQ in development - :honeybee: Community / Learning - 1Hive
[3]FAQ :honey_pot: :bee: - HackMD
[4]:honeybee: Welcome to 1Hive - :honeybee: Community - 1Hive
[5]1hive | FAQ
[6]1hive video tutorials

Proposal description:

The goal of this proposal is to acquire funding for the Fauna swarm. Working with Fauna we will develop and maintain a wiki. This is an initial funding proposal to launch the wiki. Long-term the wiki is intended to require minimal to no additional maintenance cost beyond what is being incentivized through pollen.

Key Deliverables:

  • A 1hive wiki repository,
  • Wiki Table of Contents
  • Several key documents such as welcome and FAQ will be included to help with the launch
  • Documented process for the wiki.
    • Partnering with Terra to include translations part of the process is in scope

Specifics of the initial implementation will be agreed upon by the Fauna Swarm. The process may contain some of the following but not limited to: Structure, responsibilities, incentives, training, communications, management of change (workflow), performance/metric, monitoring/review, audit, improvement, and review process.

Brainstorming a Potential Process Plan (subject to change):
The wiki could loosely be based on the Quality management system similar to ISO 9001 document control. The Wiki may have a similar look and feel as the following examples [1][2][3]. This possible outcome by no means Is all inclusive.

GitHub would be used by submitting an issue or pull request (PR) so anyone can receive ‘cred’ for their contribution. This gives everyone the opportunity to be a part of the 1hive wiki. The Fauna swarm will select review team members for the verification process (terra for translations). The review team including Fauna will be responsible for auditing content & formatting before approving and merging PRs into the 1hive wiki GitHub. Each English addition to the wiki will require 2 approvers before merging. Each translation will be based on an English revision and will require 1 approver before merging. Terra will be responsible for scoping what will be translated and into which languages. English into any translation will be managed through revision tracking. The initial work to implement the wiki and the documented process is the deliverable in return for funding. Any long-term update cost are intended to be minimal and incentivized through pollen. Morphosis may be leveraged for training members who want to learn the basics of GitHub so they too can contribute. We could potentially offer a reoccurring monthly course on submitting your first PR. Included in the scope of this wiki implementation (2-4 weeks after implementation) would be to establish a control plan and to identify any critical gaps in the process.

[1]Docusaurus
[2]Aragon Wiki
[3]Aragon Gitbook

Expected duration or delivery date (if applicable):
2 months – one month implementation plus a one month review

Team Information (For Funding Proposals)

Long-term the wiki is intended to require minimal to no additional maintenance cost beyond what is being incentivized through pollen.

  • Primary Developers ~80% funding - Luigy Lemon, Monstrosity, IEscanore, others if needed and TBD
  • Support (Fauna Members) ~20% of funding - Rayne, Jasper, Sandpiper, Harry, Blazar, lEscanore, Luigy Lemon, RogueTwo, Crisog, Dosh

Skills and previous experience in related or similar work:
I have 5 years’ experience as an ISO 9001 & 14001 auditor. Some experience with ISO 55001. Developed documentation and control process for the operations department of a 24/7 manufacturing facility with a +$100M SVOP.

Funding Information (For Funding Proposals)

Please vote on how much HNY for the above deliverables? (HNY=$245)
  • Documented process not needed just start a repo and let it play out.
  • Less
  • 8HNY ($1,960)
  • 13HNY ($3,185)
  • 21HNY ($5,145)
  • 34HNY ($8,330)
  • More

0 voters

6 Likes
DEFI TIMES - Newsletter Article and Podcast
#2

Sounds good.

I would favour git book if we can get it for free and there’s a way to allow external contributors to add content (since we are open source we can apply for a free licence). Otherwise docusaurus which I’m pretty sure is free and is a standard website and would allow contributions via PR’s.

I’d like to request any and all discussion on Discord regarding this be done in open channels as opposed to the closed Fauna channel.

1 Like
#3

A documented process outlining what? I see the long list but interested in more details.

I would like to see documentation on how to contribute. Including how to make PR’s. I imagine a good walkthrough regarding how to make PR’s would suffice over having classes in Morphosis. It’s not too long a process.

Also it would be great if we could ensure that merging automatically redeploys the wiki. I believe the websites still require manual deployment.

#4

The detail behind the list is what would be desired

Structure, responsibilities, incentives, training, communications, management of change (workflow), performance/metric, monitoring/review, audit, improvement, and review process.

The brainstormed example is a loose idea of what the documented process would look like but it’s missing a lot of detail around each of the items listed above. in the example I mostly covered a basic workflow, Roles and responsibilities. Is there a specific section that you’d like an example for to understand more or are you wanting definitions for the sections?

The process for the wiki management is in scope. Adding to the wiki is just a portion of the wiki management as we want to ensure 5 FAQs become 1 and revisions are managed properly.

Auto redeploy would be in scope. Worse case it would have been captured in the gaps analysis review.

#5

A few challenges we will have with these software packages.

  1. Will we be able to make it so everyone can contribute?
  2. How will we incentivize the wiki so we get the highest quality at the lowest cost (what we are willing to pay).
    • I don’t think we want to come back to the 1hive every month asking for a budget to maintain a wiki. We may want to consider pollen as the long term solution here.

It is possible from this wiki budget we could set aside a few honey to put a bounty on making some updates to pollen if needed.

#6

I don’t personally think a budget for wiki contributions is necessary, especially if we go the Docusaurus/Github route as Github PR’s provide pollen rewards, I think that’s enough. I think it’s a good idea to pay for management of the wiki though.

If we use Docusaurus with Github PR’s, how do you think it would be useful to modify pollen? Or is this just if we were to use a non-PR enabled service like GitBook?

Also I’ve had another look at GitBook and it doesn’t look like you can allow external contributors to make drafts of content without having the ability to also publish it, which wouldn’t work for us. I may be wrong, curious if someone else can find a way. In which case I favour Docusaurus. Also still open to alternative suggestions but Docusaurus looks pretty nice and it’s free.

1 Like
#7

The things I think would be useful to see are a description of the expected overall structure and individual page layout/structure for contributors, user and admin responsibilities and a walkthrough showing how to contribute.

From this list:

“structure” is covered above.

“incentives” I’ve shared my opinion in a previous comment.

Presumably by “training” you are referring to a contribution guide?

I’m not sure what you mean by “communications”.

“responsibilities”, “management of change”, “monitoring/review”, “audit” and “review process” all sound like they fit into the same category of user and admin responsibilities.

By “performance/metric’s” are you referring to discussion regarding the application of analytics to infer what in the documentation site seems most important to users? That could be useful.

And by “improvement” are you referring to how we might improve the documentation in the future? Or can you elaborate?

2 Likes
#8

I don’t personally think a budget for wiki contributions is necessary, especially if we go the Docusaurus/Github route as Github PR’s provide pollen rewards, I think that’s enough. I think it’s a good idea to pay for management of the wiki though.

Correct, this is the goal. Do reviewers of PR’s receive pollen? If not this is a gap that needs to be closed.

how do you think it would be useful to modify pollen? Or is this just if we were to use a non-PR enabled service like GitBook?

Correct, if we go with a non-PR enabled we would need a solution.

#9

The things I think would be useful to see are a description of the expected overall structure and individual page layout/structure for contributors, user and admin responsibilities and a walkthrough showing how to contribute.

Yes, such as an editorial policy/process. I haven’t completed this as it is part of the expectation. These policies/procedures along with the content is what the reviewers will use to ensure consistency/compliance. All these policies, processes, and procedures are referred to as the wiki management system.

image
image1144×645 86.8 KB

Presumably by “training” you are referring to a contribution guide?

Training may include but not limited to partnering with Morphosis to offer a ‘How to enter an issue and PR into GitHub’. It may include a procedure for formatting & layout standards,

I’m not sure what you mean by “communications”.

Mostly expectations around managing revision history between translations, other communications such as notifications from GitHub are mostly tied to responsibilities. More importantly capturing any changes to the wiki management system will need to be communicated.

“responsibilities”, “management of change”, “monitoring/review”, “audit” and “review process” all sound like they fit into the same category of user and admin responsibilities.

Yes, process should be documented.

By “performance/metric’s” are you referring to discussion regarding the application of analytics to infer what in the documentation site seems most important to users? That could be useful.

The structure for the wiki will have similar sections as the wiki management system itself. We will need to archive data for users to go to. Separately from archiving data for the 1hive, we may find that we need to monitor some quality, service, and/or productivity/cost metric(s) to ensure we have an effective control plan. The goal being, what is the easiest solution, that provides us with the best product at the lowest cost. Maybe a dashboard were some output is tracked that anyone can check to say, yes wiki is working. Maybe it’s as simple as a link to the github using ‘insights’ or maybe we find the wiki is self sufficient without any mention of how to monitor it. This would need to be evaluated in the gap analysis review after implementation.

And by “improvement” are you referring to how we might improve the documentation in the future? Or can you elaborate?

The improvement is strictly improvement process for the wiki management system.

1 Like
#10

Reviewers of PRs do receive cred, yes. It’s less than the creator of a PR, but I think it’s a 1x weight, whereas PRs are an 8x weight. This weight can also be changed.

1 Like
#11

I don’t believe this is a gap that needs to be closed, I don’t think the work involved in reviewing content is going to be significant. Fauna members who admin this are currently compensated through the swarm so can consider that as compensation. I think the overhead of creating a system to pay reviewers isn’t worth the hassle. Perhaps Pollen can be modified to pay more for reviews somehow and we can revisit in the future if reviewers are complaining or reviewing content stops.

Personally I think if you intend on addressing all of the points in the diagram, I think you’re overcomplicating things, at least for the initial release.

In the short term I don’t think we need to partner with Morphosis. I think to begin with we just need to create a clear guide for how to create a PR using Github against this project, that uses the correct layout/structure. In the long-term perhaps Morphosis can work on a web-dev course that could be related to this, but in the short term we should just focus on an MVP.

I don’t think we need to archive data, at least not to begin with, especially if it adds time to completion.

I think we want an MVP wiki with the documents outlined here 1hive Wiki Proposal to which we can later consider adding:
Financial incentives for reviewers.
Performance/metric’s.
Archiving data.
A fleshed out wiki management system.

We should start with the minimum required. I have faith the current reviewers have a pretty good idea what the wiki should say, they’ve done pretty well up to now with forum posts and additions to about.1hive.org so I don’t think the review requirements need to be that extensive. What’s most important is we get the wiki infrastructure setup and some guides for how to contribute. Then we can refine who manages it and how.

2 Likes
#12

In the long-term perhaps Morphosis can work on a web-dev course that could be related to this, but in the short term we should just focus on an MVP.

I plan on creating a curriculum for some sort of dev course/dev series. This will likely take awhile to create though, and I’d be interested in feedback on what languages, topics etc would be most interesting to teach for our needs.

2 Likes
#13

I agree generally with @willjgriff . Usually simpler is better.

It could be part of a job. Frankly when it comes to documentation I think perhaps buzz might be more suited to this since it is all part of the information presentation of 1Hive to the world generally.

I agree with this comment. Again simpler is better.

Again adding unnecessary complexity. What data? There are a lot of data metrics an organization needs relating to sales, customer retention, product complaints/support/service, company performance, etc. This all looks like scope over reach to me.

Also as a comment. There are a few reasons I did not continue to attack a new FAQ generally but was just collecting data.

  1. Needed time to separate what is fixed and mostly unchanging informationally from what is clearly a moving target (i.e. mostly settled - Metamask RPC issues, how to buy/sell HNY, Honeyswap, LP rewards which seem to be well known now, vs. the moving targets like Celeste, HNY issuance, proposals, Pollen/sourcecred which is still in change mode).
  2. Addition of new channels, changes to sourceCred, Faucets, operational details, support channels, new swarms, new faces, people etc. all make doing a definitive information resource difficult because so much is still evolving.
  3. Integration of what was information that was basically fixed into a tight presentation format against the 1Hive site as well so look, feel, navigation was natural vs. clunky and all over the place. It was my hope once I could settle the fixed from fluid to just integrate the fixed/fluid with the 1Hive site. Things are still moving pretty fast here so I don’t see this information job as a simple nor an easy one. There are also a fair amount of complications that are non-trivial for new users - conviction voting, dandelion voting, use of Aragon for swarms, issuance and HNY outstanding, pros/cons of LP providing, proposal submission guidelines, etc.
  4. It was my hope once infrastructure work settled somewhat that perhaps then would be a better time to get documentation in order. Look at documentation from what was going to be fixed vs. trying to hit and constantly miss a moving information target. Hence again a reason to look at this simply and not overly complicate as the larger the scope here the less nimble one can be to respond to changes. Legacy is a real issue and the more one makes the more one has to maintain it. So finding the right balance of what 1Hive users/need vs. what 1Hive might want as a long term goal needs to be dynamically managed.

In general I think 1Hive has done pretty well with not so much resources. I would rather focus on key jobs that need to be done, doing them as simply and as quickly as possible and then cycling back through as things will tighten up and change and try not to allow scope creep to then become HNY proposal creep. Trying to overlay what a $100M company needs or should have onto a .5M company is probably overkill. Small companies do just what is needed, when they need it because they often don’t have the capital (both in labor and in $$) to do what their larger peers do.

2 Likes
#14

Personally I think if you intend on addressing all of the points in the diagram, I think you’re overcomplicating things, at least for the initial release.

It is not as complicated as it appears. Note the example I gave above about a metric. We may or may not have metric(s) and to what extent is tbd. What is important is to consider each of these steps and to provide a professional wiki requiring as minimal maintenance as possible.

In the short term I don’t think we need to partner with Morphosis. I think to begin with we just need to create a clear guide for how to create a PR using Github against this project, that uses the correct layout/structure. In the long-term perhaps Morphosis can work on a web-dev course that could be related to this, but in the short term we should just focus on an MVP.

The scope of the proposal can change. I am providing what can be done. I believe that it is important to go through the ‘checklist’ and make sure we have reviewed all protentional scenarios. We do not have to have pages of documents and overcomplicate the process but someone needs to do the work. We need to remove as many hurdles as possible to make a self sufficient system that results in a professional wiki site. The community determines what they are willing to pay. Based on what 1hive believes a wiki management system is worth will determine scope of work. We can start slow and maybe just offer 1 HNY for a 1hive wiki, I wouldn’t do it but maybe would could get some traction and someone else would bid on the job.

I don’t think we need to archive data, at least not to begin with, especially if it adds time to completion.

At a later date people can add and build the archive. I should just be available.

I think we want an MVP wiki with the documents outlined here 1hive Wiki Proposal to which we can

What I am hearing your proposal is make a wiki repo and make a link. We don’t need a management system for a wiki. Let any existing systems eventually adapt to it. I suspect depending on the poll results this can be the solution.

#15

See other response on post above.

It could be part of a job. Frankly when it comes to documentation I think perhaps buzz might be more suited to this since it is all part of the information presentation of 1Hive to the world generally.

I don’t agree with buzz doing this in current state today only because we need extensive focus on marketing and I don’t think we want to distract them with a wiki site, imo. It will pull them too thin, but maybe eventually.

[
] Look at documentation from what was going to be fixed vs. trying to hit and constantly miss a moving information target [
]

The development of the system is difficult the system it’s self is almost invisible and easy. Your statement I believe reinforces the need for a clearly defined system. However, I strongly support a more modest route of not creating a system at all and just developing a wiki repo if that is all that is desired. I just hope it is more than 2 people making updates to the wiki
 Amount on polls will decide, we don’t want xfandom scam posts on our main page (see pic). Thank you for your input, a lot of work to do, we will get there in time.

image

#16

I suspect you would want the courses to match the courses Terra has selected for translation.

#17

I think that this is a really helpful proposal. If it’s possible to set it up on a free platform then it’s useful for keeping costs down, but in the longterm it will probably require a certain amount- even if it’s just nominal- maintenance if it’s to remain relevant over time. My question is: do you have a criteria/ process/ protocol for ensuring quality control over the information inputted to the wiki site ? Meaning, will your criteria be, inherent expertise, inherent readability, creds received, number of views and, or posts- or will it just be left to the judgement of the Fauna team ? Thanks

1 Like
#18

Welcome to 1hive and congrats on your first post.

set it up on a free platform then it’s useful for keeping costs down

GitHub is free and likely the solution because of the open source format, notification process, and its existing tie in to our sourcecred process.

but in the long-term it will probably require a certain amount- even if it’s just nominal- maintenance if it’s to remain relevant over time.

The goal is to make is as decentralized and visible as possible. I am not sure there will be a long term budget needed. Worse case would be $50/mo. outside of pollen.

My question is: do you have a criteria/ process/ protocol for ensuring quality control over the information inputted to the wiki site

I don’t have this answer perfectly laid out. At a high level this is needed but to what extent? Normally you perform an assessment and determine high, med, low impact. However, we don’t want overcomplicate the work of auditors. An intuitive solution is needed, the more a user has to remember the lower the success rate. The high, med, low level impact can also be applied to creating the policy/process/procedure. So maintain success rate you just focus on critical few. In regards to who audits. initially it would start with the swarm and that swarm can grow an shrink based on the needs. If have a lot of wiki PR’s you need more auditors. How they are selected may need to be determined. that would fall under responsivities training and potentially planning/contingency planning.

Slightly off topic of your statement but to give an example for a solution which doesn’t have to be complex:

  • If we have the following finding weighted as high impact - What if we don’t have enough people as auditors? Solution always have a minimum of x auditors.

That simple, the key is being sure the majority of high impact failures are identified and some type of solution is in place that is all a management system is.

Hope that helps

#19

This is a well done proposal @Monstrosity, and I think this work is clearly valuable.

As someone that’s spent the better part of 10 years doing technical writing at tech companies, I have some strong (but weakly held) opinions here.

Scope

I agree with @willjgriff and @Eth_Man that building out this comprehensive content management system, processes, etc. is not needed at this stage. The system ideas are good, but I’ve generally only seen systems of this complexity at larger companies managing many hundreds or thousands of pages of documentation. I think just a wiki, repo, and something like a well-written contributor guide should suffice.

Price

Pricing something like this is tricky. Typically, technical documentation is priced in $/hr, which can be quite high (like $50-$100/hr in the US for experienced talent). Or, sometimes it is priced per word. Estimating the cost of just the content in wiki pages would be very difficult without a detailed layout of all proposed pages. I voted for 13 HNY ($3,185) just because that was my first gut feel. But not terribly confident that isn’t a lowball or highball, depending on how the scope and implementation plans play out.

Tools

Haven’t checked out wiki tools in a while (there are many), but SourceCred uses Docusaurus for its docs and I think it’s working well. We have it configured so merged PRs automatically go live, so publishing is easy.

Security

As far as permissions go, I’m not a security expert, but while I personally favor wikis anyone can edit, I’m assuming malicious activity could be very costly here. E.g. inserting links to phishing sites, griefing from trolls, etc. Using GitHub and PRs provides a nice level of review that isn’t too costly, except for those that don’t know GitHub–a common access issue. But, if just editing pages, GitHub has made it really easy to just edit much like a normal editor, then automates all the git stuff under the hood.

Using SourceCred

I’m biased, obviously, but think SourceCred could be useful here.

As @befitsandpiper mentioned, PR reviews do mint Cred. If you go to the explorer page in the 1Hive pollen instance, there is a ‘view weight configuration’ button at the top. This will show you the weights for GitHub. Currently PRs mint 8X the Cred as PR reviews.

image

You can change the weightings. While a good deal of thought has been put into the default parameters, they can always be better tailored to a specific use case.

We’ve been paying for docs in SourceCred using the the GitHub plugin. No complaints, except that it can be hard for maintainers to tell how much Cred any given contribution will generate. But this is an issue generally, not just with docs. Afaik, we’re just including the sourcecred/docs repo with the code repos.

A while back, I did some research into using SourceCred for docs, and found promising results.

One possible issue is calibrating payouts so they fairly compensate this work. Minting different amounts of Cred per repo has been discussed, but not sure the status of that.

Here, I think you’d need consistent, enforceable guidelines. E.g. PRs for typo fixes are OK, but if you submit a bunch of these in a row, the maintainer may ask you to put them in a single PR to prevent “Cred farming”. In my experience, the GitHub plugin minting Cred on PRs can result in wonky valuations on individual PRs. But over time, contributor Cred scores tend to converge on the ground truth.

One issue could be the “burstiness” of doc writing. If most of the pages were written in the first couple weeks, and the amount of HNY/week from pollen is fixed, then PRs from that burst of activity could get paid less than those submitted in a slow week.

I wonder if it makes sense to have a fixed budget (separate or folded into Fauna) for the initial buildout, then use Pollen to reward ongoing maintenance, which might be significant actually. I agree with @Eth_Man that the changing nature of the content is already problematic. I’ve worked in companies that wouldn’t document anything unless it was “95% stable”. The underlying tech here seems less stable than that at all times. While i do think nailing down what can be nailed down is super valuable, and I support this proposal generally, I suspect the wiki will need relatively active on-going maintenance as new info comes to light.

3 Likes
#20

Thank you for feedback,

Scope: [
] The system ideas are good, but I’ve generally only seen systems of this complexity at larger companies managing many hundreds or thousands of pages of documentation.[
]

I think I am leaning towards proposing milestones so people would be more comfortable with a 2-3HNY proposal. Although I do not think it is as complex as it appears, it is a lot of work. Put simply, the builder should consider all complexities, prioritize failure modes, and implement solution/stop gaps. This can be done by using any project management approach one wants to use. It is just my preference to be guided by the ISO management system for this project as I have a lot of experience with it and think it is relevant to this project. I will likely still reference if we take a phased approach.

Estimating the cost of just the content in wiki pages would be very difficult without a detailed layout of all proposed pages

Upon releasing the final proposal I will make the deliverable more clear. As content will be limited due to anyone being able to do this. The majority of the work will be developing a process that is sustainable.

A while back, I did some research into using SourceCred for docs, and found promising results.SourceCred for documentation One possible issue is calibrating payouts so they fairly compensate this work. Minting different amounts

Thank you for the article, this looks really awesome. This is an example of what I mean when saying, “It is possible from this wiki budget we could set aside a few honey to put a bounty on making some updates to pollen if needed.”

changing nature of the content is already problematic. I’ve worked in companies that wouldn’t document anything unless it was “95% stable”

My experience is the most successful companies are those who have the lowest barrier for making updates and update the actual current state not future state or historical state. Thanks again for feedback, you have some good ideas that will be helpful in the implementation.

2 Likes