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.
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.
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.
A few challenges we will have with these software packages.
Will we be able to make it so everyone can contribute?
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.
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.
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?
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
Maintaining a wiki is a cluster.
It can be super frustrating because you end up with a lot of empty linksâŚ
Idk if this is standard, but the Open Source Ecology wiki was set up so that if you searched a page and it didnât exist one was created. IF the wiki is clean and usable it is invaluable.
I donât know anything about Git pages. That may be a better solution.
People know what a wiki is, though, and there shouldnât be an intimidation factor.
Even some developers I know are shy of GitHub (surprised thingy), and not because Microsoft bought it.
Documentation is ESSENTIAL to the success of a project, especially this early documentation. Ten years from now this is where the payoff will show⌠what we put into documenting now will save time and repeated efforts later.