NEAR Wiki Development Plan - Feedback Requested!

[David_NEAR]

What is the NEAR Wiki?

The NEAR Wiki was proposed and established in this thread:

[Done] Establishing NEAR Wiki

Wiki has been established: https://wiki.near.org I would like to launch a Wiki for NEAR Ecosystem and hope to gather support from community to fill it in and help maintain going forward. Reason Currently there are some info on the https://near.org page but it’s naturally limited and updated slowly as it’s designed to attract attention and route people. Future rebrand is going to just make that more clear but not going to create more place for content. Website is also maintained by the Founda…

The goal of the NEAR Wiki is:

To establish a single source of information on all aspects of the NEAR Ecosystem for NEAR Users, Developers, and Community Members (Guild, Validator, etc.).

Currently, the NEAR Wiki is live, community-driven, and built using GitBook.

Goal of the Development Plan

The purpose of this post is to propose a development plan and roadmap for the NEAR Wiki throughout the remainder of Q4 2021 and into early Q1 2022.

After completion of the plan outlined below the NEAR Wiki will be a fully fleshed-out source of information with relevant information siloed into user personas (Guilds, Users, Developers, Community Members).

The information should be easy to access, understand, and expand on.

Ultimately, we’ll be looking to leverage the knowledge of the NEAR Community in order to achieve this goal.

Development Plan Outline

The timeline of this plan is from the date of the publication of this document to the end of Q4 2021 and into early Q1 2022.

Phase 0: Migration to Docusaurus

ETA: W/C 22nd Nov

Currently, the NEAR Wiki is built using GitBook.

This was discussed in the original forum proposal and recommended by @illia here:

[Done] Establishing NEAR Wiki

Thanks everyone who participated in the vote (https://twitter.com/ilblackdragon/status/1414626912681476107) it came out pretty much equal. Did some more research and thanks to @blaze for digging through Gitbook settings. Here is my scoring based on your input: Gitbook: good layout/UI, good search, a bit complex contribution flow (either via github or need to become writer first), but editing itself is WYSIWYG which is a big plus for non engineer contributors. Interestingly there is a custom …

However, GitBook recently underwent an update which has resulted in a myriad of issues including missing and removed Wiki pages. The reasoning behind this was kindly illustrated by @jwaugh:

For anyone interested, the problem is that merged pull requests are not reflected in changes to the live wiki, so you have to disconnect and resync with GitHub to get such edits. Only direct commits are pulled into GitBook.

In response to this, James has already begun the process of Docusaurus migration:

I created a new branch in the wiki repo, set up Docusaurus, and pasted content from the other branch.

https://github.com/near/wiki/tree/main

You can see a rough draft here: https://near.github.io/wiki

Alternatively, we might use the “Wiki” feature on GitHub to align with our Ecosystem Map initiative (sending contributors to the same place):

NEARverse · near/ecosystem Wiki

The direction of this plan is open to change, nothing written here is final. I encourage any and all feedback!

Why Docusaurus?

Here are a few points in favour of migrating to Docusaurus:

• Our documentation repository will be aligned with the current technical documentation hosted on Docusaurus.

• There exist technical issues with the Github x GitBook connections which result in regular manual work

• Polkadot has done an incredible job with their Wiki by leveraging Docusaurus. We can emulate this without making a direct copy.

• It’s free (not a huge priority, but always a plus).

Phase 1 - Define User Personas

ETA: W/C 22nd Nov

Initially, and partly due to the urgency of the NEAR Wiki v1, we will base the user personas on assumptions rather than any validated user research.

Personas will form the basis of the categories for the Wiki as a whole, similar to how Polkadot has executed it with categories.

Newly Proposed Personas:

Previously there existed six personas; Developer, Validator, Guild, End-User, Investor, and Founder. I propose a reduction of these to 4 personas:

NEAR Users

General information regarding NEAR, an introduction to the protocol, and ‘how-to’ guides. We’d like to include the ecosystem roadmap that the Ecosystem Success team is currently developing.

Community Members

Content surrounding Guilds, including, but not limited to, how to join, how to connect, and how to create a Guild.

Developers

Tech-focused content will likely include the docs and developer resources.

Maintainers

Validator documentation, core protocol information.

–

The number of personas is kept intentionally low to provide a better user experience when users attempt to find the information they’re looking for.

Phase 2 - Content, Content, Content

ETA: W/C 22nd Nov - 17th December

We’ll be actively pursuing Community (and team) contributions to the NEAR Wiki.

Leveraging the NEAR Portal Guild

The NEAR Portal Guild was set up by @blaze in order to produce informative content for the NEAR Ecosystem. Through incentivization, we’ll be leveraging the NEAR Portal Guild in order to produce the required content for the NEAR Wiki.

Community BUIDLers Guild - NEARVerse Portal (aka Wiki)

TLDR of the proposal: The Community Buidlers guild is a new guild that will focus on creating and curating information throughout the NEARVerse to keep the new portal relevant and updated. The NEARVerse Portal servers the needs of the overall community to provide both a landing zone and launch pad to learn, engage and grow with the NEAR community. The guild members will be comprised of curators, writers, editors, translators, and liaisons to the NEAR core team. Purpose To curate, create, and …

–

A lot of content already exists, however it’s distributed through documentation on different websites and internal documents (in some cases).

To keep in line with the simple nature of NEAR tech, and the core tenets of decentralization, we’ll collate and publish all relevant documentation in the NEAR Wiki directly.

This phase will not be restricted to content creation but will include, quite heavily, ideation for relevant content, too.

How Can I Contribute?

After migrating to Docusaurus we’ll be sharing a guide on how to contribute - this includes the contribution process and a writing style guide.

If you’d like to join the NEAR Portal Guild and begin contributing to the NEAR Wiki then feel free to do so here:

NEARVerse Portal Guild

Feel free to respond to this thread with any questions or proposals for information which should be included in the NEAR Wiki.

Phase 3 - Review and Refine

ETA: 20th - 31st Dec

As essential and valuable as community-driven contributions are, it’s important to be conscious of the fact that the official NEAR Wiki is representing NEAR in many ways.

Consequently, after documentation is published every effort will be made to review and refine the contributions. This is focused on the content’s grammar, accuracy, and writing style.

A style guide will be developed and published to assist contributors ASAP.

Phase 4 - Community Assessment

ETA: Completion by 14th January, 2022

As with many things in the NEAR Ecosystem, there will never be a point where the NEAR Wiki is ‘complete’. As the ecosystem continues to evolve, so will the NEAR Wiki.

I propose we semi-regularly (TBD) request feedback and assessment from the Community and Wiki users. This could be rolled up into another type of user feedback initiative we take.

Could we implement a feedback feature directly into the Wiki page itself?

This is something that Docusaurus can support but it requires a certain amount of tech attention. If we don’t have this internally, we can outsource this.

How Will We Measure Success?

Docusaurus - Built-In Feedback

A part of the Docusaurus rollout would include the implementation of a feedback widget, similar to the one shown below:

The goal of this is to measure whether the information in the Wiki articles is satisfying the needs of the reader. Further to this, we’d seek to implement more granular feedback methods, including a text box, in order to understand what information seekers are trying to find and failing to do so.

Community Assessment

As outlined in Phase 4, we’ll rely on the NEAR Community and, primarily, Wiki users to gather and synthesise feedback.

–

I’d encourage you all to please leave feedback in this thread. We really want to nail the NEAR Wiki and we can only do so with your help.

Thank you!

[shreyas]

Thank you for putting this together, David! I really like the regular user feedback assessment to measure the effectiveness of the page.

I know that we’re still in early stages, but I hope the final version will have the search functionality enabled. That’ll be super useful in the wiki. AFAIK, with the combination of Algolia and Google analytics, we can actually figure out what people are searching for, and add that into the wiki if there are enough searches around that term.

From a knowledge management POV, one of the main challenge is that wikis aren’t often updated. Would be great if we can come up with a process around that- maybe assigning individuals to specific sections and reviewing it bi-weekly or something.

[David_NEAR]

Thanks for the feedback, Shreyas

All of that is noted. Search will be integrated for sure.

On the updating front; will get something developed to ensure that it’s kept up to date.

[Matt_Hussey]

Great work on this David.

What I’d love to see is more linear, cumulative learning pathways. NEAR Foundation is going to be producing a lot of educational content for total beginners to help make NEAR a super easy place to understand. Maybe we could combine these together into a duolingo style format?

[David_NEAR]

Appreciate the feedback, Matt

Absolutely! The intro screen of this Wiki is kind of along the lines of what I have in my mind for that (having thought about it for 30seconds haha)

[Matt_Hussey]

Yeah nice. I helped build this many moons ago - not suitable for the Wiki but you can see where I’d like to take learn content more broadly.

[David_NEAR]

That is absolute - thanks for sharing!

[starpause]

I was one of the supporters of Gitbook and their upgrade has been an embarrassing mess. In full support of the Docusaurus migration! Thank you for all the hard work.

[amgando]

@shreyas

with the combination of Algolia and Google analytics, we can actually figure out what people are searching for, and add that into the wiki if there are enough searches around that term.

makes perfect sense, @shreyas – this is actually a free tier of the basic search service provided by Algolia for all open source projects iirc.

they even send you a weekly report on search terms found / not found as per this screenshot – we get this for docs.near.org

[David_NEAR]

That’s ace! Will definitely serve to shape what content is needed, too - as Shreyas mentioned

[crptbrthrs]

This is great news! The more knowledge and experience a user can find in one place the easier it is to understand and come to the ecosystem! Later when it takes shape, we will be able to offer a couple of ideas for the Wiki. Another question. Will the key people of this forum be added to the WIKI with a description of their area of responsibility?

[David_NEAR]

Appreciate the feedback!

@crptbrthrs

Will the key people of this forum be added to the WIKI with a description of their area of responsibility?

I don’t think this would suit the Wiki, perhaps a thread in the forum? I think we should encourage people to keep their bios updated in the Forum, too

[crptbrthrs]

This is true for people with a certain level of knowledge about the ecosystem and about the forum. But there are even more people who go to the forum through the website and wiki. I will add, that such information on the forum is scattered in many corners and in order to collect the whole picture, people spend a lot of precious time. This is especially true for entrepreneurs - none of them will spend a lot of time on the forum, instead of finding everything in one place on the site. Please consider this possibility.

As for the forum thread this is also a great idea there are similar topics but they are not complete and it is difficult to search for them. In this case it can also be very useful especially if you somehow highlight it with a design or a hook. Quick and easy access to basic information on the way of different people is an important aspect. And the path is different for each category of users.

In this way it will help to reduce the barriers to entry into the ecosystem (I am investigating this issue).

[David_NEAR]

I find it difficult to justify a list of key people in the forum to the Wiki for the following:

• The two are separate
• It would be more suited to a forum post (which could be linked in the Forum Guidelines?)
• It’s not evergreen and would require a not insignificant amount of effort to maintain (what do we do when individuals leave, change roles, etc?)

@crptbrthrs

I will add, that such information on the forum is scattered in many corners and in order to collect the whole picture, people spend a lot of precious time

This is a conclusion which we’ve validated through the Governance Forum Revamp Plan

Governance Forum Revamp: Plan - OPEN CALL FOR FEEDBACK

[image] Click to view full image As with the entire NEAR Ecosystem, the NEAR Governance Forum is Community-driven and sculpted. Currently, there is no data in regards to the user experience of the NEAR Governance Forum. Although we can access basic metrics regarding usage, there is no quantitative or qualitative data in regards to UX. The following document serves to outline a proposal for a medium-term revamp of the Forum in which decisions will be made using a data-driven approach. Data w…

Particularly the survey which we’ve just finished synthesising data from

Governance Forum Feeback Survey - Open Call!

Now that NEARCON is in the rearview mirror the time has come to push forward at full steam with the Governance Forum Revamp Plan If you’re a Governance Forum User and you want to be involved in sculpting the future of the Governance Forum then, please take a moment to fill out the form below I’d like to encourage you to be completely open and honest, only that way will we be able to get an accurate picture of the current state of the Governance Forum. SURVEY LINK …

We’re ideating on solutions and will open up our plans to the community asap.

[crptbrthrs]

@David_NEAR

I find it difficult to justify a list of key people in the forum to the Wiki for the following:

• The two are separate
• It would be more suited to a forum post (which could be linked in the Forum Guidelines?)
• It’s not evergreen and would require a not insignificant amount of effort to maintain (what do we do when individuals leave, change roles, etc?)

That’s right, these are good arguments. And if it can improve the experience then it makes sense to address such issues.

Here will need figures and statistics to understand how things are with this. For example, how people come to the forum, what percentage of newcomers reads the rules, and so on. And based on these data, you can choose a place for this on the path of a newly arrived participant.

Thanks for clearing things up.

[David_NEAR]

@crptbrthrs

For example, how people come to the forum, what percentage of newcomers reads the rules, and so on. And based on these data, you can choose a place for this on the path of a newly arrived participant.

Music to my ears friend, thanks for the feedback!

[jlwaugh]

I think we are ready to move forward with switching the wiki.near.org domain over to the Docusaurus version. Check progress: Hello from NEARverse Portal | NEARverse Portal

GitHub - near/wiki at main

This will hopefully engage more contributors to the wiki, docs, and ecosystem map repositories. Also, I’m personally interested in revamping the Community repository.

Note on accessibility, compared to GitBook: helping contributors learn how to use GitHub is valuable for NEAR as an ecosystem.

For a quick walkthrough, feel free to grab time on my calendar here. GitHub provides great documentation as well. Part of the goal is to improve onboarding, so contributors will have more opportunities to get involved and create a positive impact.

I’m coordinating with @damian and @josh to figure out how this needs to be hosted and maintained going forward. Currently using GitHub pages.

Decisions / Actions

• migrate all content
• use Render for hosting
• DNS updates

Next Steps

Phase 1 Complete: User Personas Defined

@David_NEAR

Previously there existed six personas; Developer, Validator, Guild, End-User, Investor, and Founder. I propose a reduction of these to 4 personas:

NEAR Users

General information regarding NEAR, an introduction to the protocol, and ‘how-to’ guides. We’d like to include the ecosystem roadmap that the Ecosystem Success team is currently developing.

Community Members

Content surrounding Guilds, including, but not limited to, how to join, how to connect, and how to create a Guild.

Developers

Tech-focused content will likely include the docs and developer resources.

Maintainers

Validator documentation, core protocol information.

Phase 2: November 22 - December 17

• landing page design
• content development
• user journeys completed
• NEARverse guild organization
• other suggestions?

New Consideration

Also, thanks to @evgenykuzyakov, we now have thewiki.io built on NEAR. I’m also going to start moving some content over there, and I encourage others to do the same. Let’s find out if it can be useful to make changes associated with our NEAR accounts.

GitHub - evgenykuzyakov/wiki: wiki on chain

The main concern with a full commitment to that solution (embracing the on-chain approach) is the risk of bad user experiences involving undesirable content. I’ve reached out to the maintainer of that wiki app, and until we know otherwise, editing rogue content would be our best strategy for moderation.

Open Discussion

Evgeny Kuzyakov

Please reply with any feedback!

[David_NEAR]

Howdy team,

Quick update on the future of the NEAR Wiki.

We’re aware that many of the NF team, and the Community, have been making changes to the NEAR Wiki through Gitbook - which is awesome to see!

Currently, the NEAR Wiki is in a disorganised state. We’re seeing an increase in the amount of content being created to publish there, but there’s still a certain amount of disarray when it comes to the organisation of it.

To keep people up to date, the next steps are as follows:

• Tomorrow (2/12)- Reorganise the Wiki into categories and subcategories with the aim of making it easy to navigate and find the information you’re looking for
• This week - Synch with James on the migration to Docusaurus. Once the Wiki is aligned on Gitbook, migrating to Docusaurus is straightforward.

Reorganisation

Before merging the reorgonisation of the forum and pushing it live, we’ll be opening it up for Community feedback (as always! ).

So there’s no surprises, this is a high-level overview of what we’ll be looking to achieve:

We’ll be building something as concise and easy to understand as this, but expect it to be a little more granular and geared towards the NEAR Ecosystem.

[erik.near]

What’s the update here?

[David_NEAR]

This is the latest update:

NEAR Wiki - Reorganisation & Update - Request for Feedback

Happy Friday! Chiming in with an update on the NEAR Wiki Development Plan. https://gov.near.org/t/near-wiki-development-plan-feedback-requested/9123/19 Reorgonisation The NEAR Wiki organisation has been completely overhauled and pushed to the wiki.near.org The goal of the reorganisation was to make the Wiki simpler to navigate, less cluttered, and more concise. Old Layout New Layout Please do take a moment or two to check the new layout out and let us know what feedback you guys …