Redo learn and participate

[jlvandenhout]

I think that the learn and participate sections should be restructured, partly rewritten, and shrunken down. I like to hear your opinions. Let me start with my own below.

Learn

The learn section should read like a book, starting with a gentle, non-technical, catchy introduction to our ecosystem and slowly exposing more and more information to ease the reader into the wealth of knowledge to fully comprehend the ecosystem, expanding on terms used and being careful not to overwhelm the reader. Also, we should respect the time of the reader and not claim more of it than necessary.

I think we can do better on several points:

• Currently, our book starts with a long, highly technical, and perfect explanation of what we are not, with unexplained abbreviations and terms that are unfamiliar outside our community, to finish off with explaining the implementation details of current consensus, which is a field in its own right.

• The introduction section suddenly ends with seemingly misplaced text and tables about energy efficiency. It looks like we are showing off. At the least, we should move this further down.

• The networks section mentions the names and version numbers of the current networks, but the more common mainnet and devnet are nowhere to be found in the headers.

• Before we continue to the bright future of IOTA, here is a page full of random slides for you.

• A few headers could be clearer to guide the reader. For example, I think Firefly should be something like "mainnet wallet" or "managing your tokens" or similar. We can explain in the text that Firefly is the officially supported and current wallet. There could be others in the future.

Participate

Concerning participate, we should have a good look at what we want in there and how we present it.

Some things that I think need to change:

• Almost the whole "about nodes" section belongs in the learn section.

• I think we should rewrite the "node software" section to explain how to decide what software to look at, not just listing the different node implementations. Those names don't mean anything to someone new to the ecosystem.

[lucas-tortora]

@jlvandenhout I must say I agree on everything except approaching it like a book. I think in this day and age, users will most likely land in the wiki through a search engine or social network links. This means the entry page can be different for each user; they could even start at the same page but on different headers. This means the sections should have a linear and thought-out approach, as you say, but we should not expect the user to have read 1 and 2 if he's on 3.

On a side note, I think it could be worthwhile rethinking the "Participate" section header in general. In my experience, it's usually the one where it's hardest to get any content as it's typically social network links, run a node, or "contribute to projects" which works best in project docs if you ask me. Off the top of my head, I think "grow", "innovate", "integrate", "share" could have a nice ring to them.

[lucas-tortora]

scratch innovate, it's used by Apple.

[jlvandenhout]

Good point on the book versus "linear, but potential entry in the middle" way of thinking about the learn section. So several points I take from this:

we should not expect the user to have read 1 and 2 if he's on 3.

• We expand abbreviations on the first mention in that page.
• We either explain terms on first mention or link to the glossary on first mention (UX can be improved with Feat - Glossary tooltips #196).
• Rather than enforcing a flow from high to low level explanation on the macro structure of the learn section, we should focus on a structure that logically makes sense and at least feels linear.
• We enforce high to low level explanation on the page level.

I think it could be worthwhile rethinking the "Participate" section header in general. [...] as it's typically social network links, run a node, or "contribute to projects" which works best in project docs if you ask me.

I disagree with renaming participate, but I agree with your point on the content, so here is my proposal for an alternative approach:

We keep participate, but we rewrite and repurpose it to provide the reader a guide where to go to based on why and how they want to participate. Basically a decision tree in text. So rather than just listing and pointing to node implementations, which don't mean anything to anyone not familiar with the ecosystem yet, we explain that we have different networks with different purposes. If you want to want have your own access point to mainnet and contribute to the safety of the main network? Use Hornet or Bee nodes and here is how to set it up. Do you want to have a glimpse of the future of IOTA or want to try out smart contract functionality? Here is the GoShimmer and Wasp nodes and how to set them up. Do you want to discuss something? Here are our socials for different purposes.

Wdyt? Or would you then still rather rename the section.

[lucas-tortora]

Sorry, I think I missed this notification. I'm all for the decision trees :) . I don't the section name per se isn't really a problem as much as it's a constraint on how we organize the wiki at the top level. Though the index page is really nice (I love the bots), forcing this structure for the sidebar seems like it's counterproductive to the UX, as it forces us to categorize everything within those three tags instead of what the users are looking to find. As well, Build will always be much bigger than the other categories.

[JSto91]

Hey, thanks for opening up this discussion.

I also feel the Learn and Participate Sections need some changes. While I am not a Dev I hope my pov is some sort of help.

--

"Currently, our book starts with a long, highly technical, and perfect explanation of what we are not, with unexplained abbreviations and terms that are unfamiliar outside our community, to finish off with explaining the implementation details of current consensus, which is a field in its own right."

I agree here.

For which group of people do we want to provide information? I think the Learn-Section should be the place for beginners.

If we want to make it more attractive for new people, especially people that never dived into Crypto itself but are interested, we have to keep it as easy as possible.

I would even go as far and say a „Basics“ category would be nice.

Keywords like Smart Contracts, DLT, etc explained in 1-2 sentences if possible.

Imagine if someone on the internet is interested and asks where he should start reading about DLT etc
„Visit the IOTA Wiki, they have a good starting point for beginners“

And this is where we might/can reach more people, also potentially interested in IOTA since they have the opportunity to continue reading.

--

Learn

Introduction - This needs to be split into subpages in my opinion and should focus on IOTA

• What is IOTA?
• The Tangle
• Coordinator
• What makes IOTA special? (Feeless/ Sustainable/ etc)

Value Transfer – I think the idea with the example is nice, but…complicated explained(?)
It kinda reads like Charlie needs to write some sort of program to execute a simple transaction.

I hope you get what I mean.

Energy efficiency – I think that this belongs somewhere else. For example an extra section „Tangle under Trial“ or whatever. There could also be added other results from stress tests or something – just an idea

Firefly user guide – „Staking“ and „Wallets“ should be split and be subpages

Firefly Ledger – should be also a subpage under user guide

Networks – Shimmer and Assembly are missing. They were already introduced on the „Staking“ Page. I know it was said „we will only mention currently available stuff“ but I think this is important and should get the attention at the right place.

--

Something more of a general issue is in my opinion: Trying to squeeze everything on one page.

For example, the Introduction page has a ton of information and it feels kinda overwhelming, at least for me.

Don’t get me wrong, I don’t think every little topic in the content should be a subpage, but there need to be some clear cuts when a topic is done.

Also: We need more spacing between topics in the content.

Hope it didn’t feel like a rant ❤️

Btw what do you guys think about a Feedback form? We could get valuable information from the community what needs to be improved. What's too complicated etc.

[lucas-tortora]

Hi, just putting it out there so we can think about it, but what would you think about getting rid of the whole "Learn, Participate and Build" altogether. At the moment, this is our first top-level hierarchy, and it's not precisely intuitive what goes where. We could make the whole navigation more topic, action, and type-oriented. This is similar to the current Build Welcome Page concept.

The main UX change would be having a "one sidebar to rule them all" sort of thing. It shouldn't necessarily have all the elements from the build section at a glance, as this would probably make it too big. It'd just have all the current Learn and Participate articles, key explanations, how-to, and reference articles under each topic.

A very simplified example:

.
├── Node Software/
│   └── Key concepts/
│       ├── [About Nodes](https://wiki.iota.org/participate/support-the-network/about-nodes)
│       ├── [Node Types](https://wiki.iota.org/participate/support-the-network/node-software)
│       ├── [Nodes 101](https://wiki.iota.org/hornet/getting_started/nodes_101)
│       ├── [Security 101](https://wiki.iota.org/hornet/getting_started/nodes_101)
│       ├── Hornet/
│       │   ├── How to/
│       │   │   └── [Run a Node](https://wiki.iota.org/hornet/getting_started)/
│       │   │       ├── [Use the apt repo](https://wiki.iota.org/hornet/getting_started/hornet_apt_repository)
│       │   │       ├── [Use docker](https://wiki.iota.org/hornet/getting_started/using_docker)
│       │   │       ├── [Use docker compose](https://wiki.iota.org/hornet/getting_started/using_docker_compose)
│       │   │       ├── [Configure Your Node](https://wiki.iota.org/hornet/post_installation)
│       │   │       └── [Run a private tangle](https://wiki.iota.org/hornet/getting_started/private_tangle)
│       │   └── Reference/
│       │       ├── [API Reference](https://wiki.iota.org/hornet/api_reference)
│       │       └── [Configuration](https://wiki.iota.org/hornet/post_installation/configuration)
│       └── Bee  /
│           ├── How to/
│           │   ├── [Run a Node](https://wiki.iota.org/bee/setup_a_node)
│           │   └── [Configure Your Node][(https://wiki.iota.org/bee/configuration)
│           └── Reference/
│               └── [API Reference](https://wiki.iota.org/bee/api_reference)
├── Smart Contracts/
│   ├── Key concepts/
│   │   └── [...]
│   ├── How tos/
│   │   └── [...]
│   └── Reference/
│       └── [...]
└── [...]

We should still follow the How to, Key concepts (explanation), Reference, and Tutorial structure within each project and add a link or switch with the main sidebar. I think this would have three main benefits for the user experience:

1. All the project docs will follow the same basic structure: Naturally, this is good for users as they'll be able to navigate the wiki more intuitively.
2. It will force us to make an inventory of all our current content: We will start seeing the wiki as a whole rather than in three sections, one of which is much broader than the others. If we do this properly, it will reduce content and add better references within the content itself.
3. It will force us to categorize and separate all our content: As @JSto91 said, we are trying to squeeze too much into one page. If every page has to fall into only one of the content type categories (how-to, key concepts, reference, or tutorial) and address only one topic, the content will necessarily be on point.
4. Users will be able to search content by type: If everything is categorized by Content type, topic, and project (if appliable), the Algolia search function could automatically tell the users what type of content the current results are. Additionally, we could add a filter for content type categories.

We can keep the current index page, but we could consider adding pages like the one in the Build Welcome for Learn and Participate as well, to steer the users in the right direction.

This is easier said than done. However, the IOTA Tech Writers are already tagging all the content with said categories, so the process should be a bit simpler than one would anticipate.

[lucas-tortora]

Can we just look at the usage stats and see what the users actually do?

[jlvandenhout]

Sounds like the most reasonable thing to do. Not sure how to approach that, no expert in that kind of thing. So we need someone who is. UX team again?

[lucas-tortora]

Most of the usage data is intuitive to interpret, at least on this sort of "macro" level. Which pages have the most visits, hot areas, most clicked links, reference pages, bounce rates (pages where the user lands and exits almost instantly), and user searches should give us an overview of what the users are doing and hopefully what they are trying to do.

Personally, I doubt anyone is just orderly going through any of the sections in an orderly manner. At best, I think they land on X page through a search engine o social network and read up on that. Project docs outweigh the Learn and Participate sections in a 5 to 1 ratio if we are going by article count, so since most of our content is targetted to a knowledgable audience (at the bare minimum they should be attempting to code or run something) we should give them some credit and assume some of them know what a node, smart contract, wallet, etc. are. This doesn't mean we should ostracize users who don't code, but that we should cater to each user type in a different manner. We could have different "paths" we lay out for users, from the most basic like "what is IOTA" leading to using any and all of our projects.

But without actual usage stats, this is just an opinion, and given the scope of the task at hand, I think we should do some careful analysis based on facts rather than guesses.

[jlvandenhout]

But without actual usage stats, this is just an opinion, and given the scope of the task at hand, I think we should do some careful analysis based on facts rather than guesses.

I agree, this is why my initial opinion was to adhere to what the UX team came up with, starting with the action based top level.

I personally am not in favor of one or the other approach. The only argument in favor of keeping the action top level for me might be it allows incremental changes. Start unifying the (current) build section using Diataxis and separating tutorials is already a big step forward imho.

But if like you say topic based is fine for UX and we can pull it off in one go, I'm fine, but then the big question for me is where to put the content that does not neatly fall under a project?

[Schnurzle]

Hope that I can give also a small input from user-perspective, in short I don't really like the Build, Participate and Learn categories. From my point of you with names like 1, 2 and 3 it would be the same result: you'll never know where you have to search.
The main problem (what I think) is, none of these words is defined and (I will repeat that, sorry for that) the complete wiki is about learning.

• Everything, the complete wiki is about learning. It is the reason why it exists. At the moment, that category is more or less a type "beginner guide" and especially not learning in total.
• I participate with my hornet node. I don't build. Other users may "build" with their hornet nodes. Isn't buying/trading IOTA a type of participation too?
• If you want to build - I'm not a developer, but I think it is good to know how the messages within the IOTA network are defined. So if you want to build and if you need to know that, you have to check the learn section.

That's why I really like this idea of reorganization. :)

[Dr-Electron]

Ok, so it sounds like we came to something like an agreement
Let me summarise what we discussed here. Also this will not be the final form. It's mostly just a restructure of the current content. We then still need to remove duplicate and restructure some content.

About IOTA/
├── IOTA Token
├── Wallets
├── Networks
├── Media Library
├── Research
├── Future of IOTA
├── Glossary
├── FAQ's
├── Use Cases
├── Funding
├── Partnerships // Should be part of iota.org I guess?
└── Community/
    ├── The Community
    └── Contribute To Wiki
Networks/
├── Getting Started
├── IOTA/Shimmer Docs
└── Coordicide(IOTA 2.0)/
    ├── GoShimmer Node
    └── Coordicide Specs
Libraries/
├── Client
├── Wallet
├── Stronghold
├── Identity
└── Streams
Smart Contracts/
Nodes & INX Plugins/
├── About Nodes
├── Become a node operator
├── Node Software
├── Hornet Node
├── Bee Node
└── Chronicle Permanode/inx plugin

This would also mean we change the Navbar on top to something like:

About IOTA        Networks        Libraries        Smart Contracts        Nodes

Some things that we still need to discuss:

• Should wallets get it's own top level section? Or only Firefly?
• We may have single page overview for Libraries, Networks and Nodes in About IOTA
• Do we really want a Networks section?

[lucas-tortora]

• I just realized that there is also "SWARM" which would fall under "Community Project" i guess. How would this be handled? Add a new page under "Nodes & INX Plugins"?

I think so, though at the moment the wiki is mainly IF focused, being a wiki we could really broaden the scope to include all the relevant parts of the ecosystem. This would probably encourage these projects to build better docs, and want to get listed in the wiki. Which in turn would probably bring some of their users into the wiki. Wdyt?

[Dr-Electron]

Building time for the wiki just increased by 2 weeks

[Dr-Electron]

A misunderstood you

[Dr-Electron]

Yeah we need community sections also for wallet and so on. So they can list themselves there. But it should be clear that those are community projects and not verified by IF

[Dr-Electron]

Near for example has also nice pages like this for community projects/communities in general:
https://awesomenear.com/categories/defi
https://near.org/guilds/

That's why I always wanted to give some love to iotaup