Website outline

[karimStekelenburg]

I have been playing around with the sidebar structure by myself for a bit, but I'd like to open this up for discussion so we don't have to refactor n+1 times.

Top bar

Currently, the top bar has two items as displayed below:

Later on, I'd like to add additional items to the top bar for things like generated API docs.

Guides sidebar

The current structure of the sidebar in the Guides section looks as follows:

Intro
Getting Started/
└── Installation/
    ├── Node.JS
    └── React Native
Concepts/
├── Agents
├── DIDs and DIDComm
└── Platform and Environment
Tutorials/
└── Agent Setup
Ecosystem/
├── Aries Framework JavaScript
├── Aries Framework JavaScript Extensions
└── Aries Mobile Agent React Native (Bifold)

Note: the categories displayed as folders in the snippet above (Getting started, Concepts, etc.) are not just foldable menu items, but they also have their own page.

There a short description of what my idea was for each category/page:

Intro

Mostly a welcoming page that gives an introduction on the structure of the guides and where you can find what.

Getting started

Everything needed to get up and running, regardless of your use case.

Getting started/Installation

Short introduction on supporting multiple environments and install instructions for @aries-framework/core

Getting started/Installation/Node.JS

Instructions on how to install Indy and @aries-framework/node

Getting started/Installation/React Native

Instructions on how to install Indy and @aries-framework/react-native

Concepts

Page that explains that the subpages under this category go over the underlying concepts useful for gaining an understanding, but do not include practical examples and/or snippets.

I will not explain the other subcategories here, I think they speak for themselves.

Tutorials

Page that summarises the tutorials under this section. I would like to make these tutorial very use case specific and all covering. This means that the tutorial covers everything (apart from installation) to implement the use case in question. In other words, every tutorial will discuss agent initialisation, creating a connection, etc. My main reason for this is that the agent configuration depends on the use case (e.g. issuers need public DIDs, pure basic messaging doesn't require a ledger connection, etc.) and because as a reader of a tutorial I don't like to hop between pages too much.

Additionally, I'd like tutorials to cover all roles involved. For example, a tutorial about credential issuance should have snippets and explanation on both the issuer and holder agent, just like in @blu3beri's tutorial on Medium.

Some examples of tutorials I currently have in mind:

• Sending basic messages
• Issuing a credential
• Verifying proof
  • Working with predicates (ZKP)
• Creating a cloud agent (REST extension)

More ideas are obviously more than welcome!

Ecosystem

I'm not too sure about this section yet, and I'm not sure the Guides section is the place for it. However, I would really like a place to explain what the individual components of what I'm now calling the 'Aries JavaScript Ecosystem' are and how they relate to one another. I've heard this question come up multiple times in the AFJ working group call, so I think it is useful. Maybe this section is better fit as a top bar item, I'm not sure. Ideas are welcome.

Extra section

Because I'd like to keep the tutorials very use case specific, I'd like to not go into depth on every function call there. However, there are common practices that deserve a more in depth explanation. For example, I think it would be nice to have a separate page dedicated to 'setting up a connection' where we can explain things like auto-accept, OOB and the optional parameters. We could add a separate menu item called 'Common practices' for this. Other suggestions more than welcome.

[karimStekelenburg]

@TimoGlastra, @blu3beri, @morrieinmaas, @anagoessens, @janrtvld, @jloleysens

If any of you have opinions on this, I'd love to hear them. You all have experience with reading documentation, so your opinion is valuable regardless of how deep you are into AFJ.

🚀 🚀 🚀

[jloleysens]

A few thoughts from my side @karimStekelenburg

The "Concepts" section has a subsection "Platform and Environment". I'm guessing here, but this could be heading a slightly non-conceptual direction? Or is this intended to a more high-level description of how things work at above-agent level. If that is the case perhaps this subsection should go first.

---

Judging by the structure, I don't think "Installation" should be a subsection of "Getting started", perhaps the can just be collapsed into the same thing? Maybe with a page that just introduces what platforms you can choose.

Getting Started/
   └ Introduction
   └ Node.JS
   └ React Native

---

Perhaps we can rename "Tutorials" to "Guides"?

---

In other words, every tutorial will discuss agent initialisation, creating a connection, etc. My main reason for this is that the agent configuration depends on the use case (e.g. issuers need public DIDs, pure basic messaging doesn't require a ledger connection, etc.) and because as a reader of a tutorial I don't like to hop between pages too much.

Mooi!

---

Ecosystem: No strong opinion here, but I guess "Aries Framework JavaScript" should not be part of its own ecosystem?

---

Extra section: I think we can reuse the "Guides" section for this? Perhaps there could be "Basic" and "Advanced" use cases captured there?

[karimStekelenburg]

The "Concepts" section has a subsection "Platform and Environment". I'm guessing here, but this could be heading a slightly non-conceptual direction? Or is this intended to a more high-level description of how things work at above-agent level. If that is the case perhaps this subsection should go first.

So my initial thought here was to explain that the framework (and extensions) run in both RN and Node, without mentioning any technicalities. I guess this could be regarded as quite 'high-level'. However, this is probably so little content that it doesn't deserve its own page and could easily be captured somewhere in the introduction.

Judging by the structure, I don't think "Installation" should be a subsection of "Getting started", perhaps the can just be collapsed into the same thing? Maybe with a page that just introduces what platforms you can choose.

I have sort of relied on the structure of a lot of repo README's for this. Install instructions are often listed under a 'Getting started' section. That being said, I do agree with nesting it under a different page. Installation sounds wack anyway LOLZ.

Perhaps we can rename "Tutorials" to "Guides"?

I've called it 'Tutorials' because the top menu already has a 'Guides' item and the 'Tutorials' section appears in the sidebar if you click on 'Guides'. I've mostly done this to avoid confusion, but if you think this is OK from a UX perspective, I'm more than willing to change it. My UX knowledge is below 0 😃 .

Ecosystem: No strong opinion here, but I guess "Aries Framework JavaScript" should not be part of its own ecosystem?

I'm struggling a bit with getting this clear, so I get your point.

The things is that this documentation is not about the framework itself, but more about the whole Aries JavaScript 'ecosystem'. There are a few other projects/repositories that have a strong relationship to AFJ (a mobile agent built with the framework and a repository that contains extensions for the framework). AFJ itself is definitely the most prominent part, but there is more.

Again, having a hard time explaining this and there is a chance this is the wrong way of approaching the docs in general. Thoughts are welcome as always!

Extra section: I think we can reuse the "Guides" section for this? Perhaps there could be "Basic" and "Advanced" use cases captured there?

I kind of agree, but I'd like to make it very clear that the 'tutorials' section is about full on, start-to-finish guides on specific use cases and that the 'extra section' is about practical examples on common practices (but not an entire walk through). We can probably make this clear in the description.

Finally, thanks for your feedback @jloleysens! If possible, I'd love to keep you in the loop in this. I think your UX knowledge can bring a lot of value here, plus since your not very familiar with the framework (yet), it helps to have a pair of fresh eyes 😄 !

[janrtvld]

My two cents:

Intro

Getting Started
GL with all the windows7/8/9/10/11/m1/m1pro/m1max/intel versions.

Concepts
I don't know how far this info goes (and this might depend on your goal with these docs), but i'd like these to be small and comprehensible paragraphs to skim over if i don't understand something. If this is not the case, maybe add a separate tab called components where you just show me the Agent or what's a Credential. Some kind of hybrid between a concept and a tutorial. I think this would be nice because when i read about the concept of an SSI agent i had no clue what that actually look like in code.

Tutorials
See above comment about components.

Ecosystem
I like this part as i still have no clue what/who bifold is. I agree the 'Guides' section might not be the place for it. You could also add it to the intro (depends on how much info it is) or to the getting started as i might need to know what these ecosystem components are before i install anything.

[karimStekelenburg]

Thanks @janrtvld! Tried to send you a Slack message just now, but for some reason it's down. I'd also love to have your opinion on UI. It's quite ugly right now, so tips are more than welcome. I will open a separate discussion for this shortly.

[karimStekelenburg]

GL with all the windows7/8/9/10/11/m1/m1pro/m1max/intel versions.

I agree. However, the architecture/OS setup is different so different (at least for now), we need to have separate guides for it. Maybe a different structure will make it look a bit less daunting tho.

I don't know how far this info goes (and this might depend on your goal with these docs), but i'd like these to be small and comprehensible paragraphs to skim over if i don't understand something. If this is not the case, maybe add a separate tab called components where you just show me the Agent or what's a Credential. Some kind of hybrid between a concept and a tutorial. I think this would be nice because when i read about the concept of an SSI agent i had no clue what that actually look like in code.

My initial idea of this section was to briefly explain the fundamental concepts of SSI to anyone who is not familiar with SSI. Examples are: DIDs, DIDComm, Verifiable Credentials, Issuers, Holders, Verifiers, etc. I agree with your point that these explanations should be brief and comprehensible. We can always refer to relating RFCs and specs to offer more info to the reader.
So I think your first guess is more in line with my initial idea. Not all of these concepts map directly to a piece of code. The concept of a holder for example is quite philosophical and cannot be described in a snippet.

This is just my initial thought tho. If anyone thinks these kind of explanations don't belong in these docs, please shout :)

I like this part as i still have no clue what/who bifold is. I agree the 'Guides' section might not be the place for it. You could also add it to the intro (depends on how much info it is) or to the getting started as i might need to know what these ecosystem components are before i install anything.

Totally agree. The different parts of the 'ecosystem' should be introduced from the beginning. This doesn't make sense at all.

[berendsliedrecht]

proposed structure:

We should keep this comment up to date with the latest proposal for the structure.

- Intro
- Getting Started
  - Prerequisites ✅ 
    - nodejs ✅ 
      - apple ✅ 
      - windows ✅ 
      - linux ✅ 
    - react native ✅ 
      - ios ✅ 
      - android ✅ 
      - bifold
    - Setup
- Concepts
  - Agents ✅ 
  - DIDs and DIDComm ✅ 
  - Agent config ✅ 
  - TODO
  - advanced
    - TODO
- Tutorials
  - Create a connection
  - Issue a credential
  - Verify a proof
  - advanced
    - wallet storage
    - wallet migration with new afj version