Menu Perestroika Proposal: App Deployer / Recipe Maintainer / Community Member #26

New Issue

3wordchant · 2021-11-17T09:57:46Z

3wordchant commented

2021-11-17 09:57:46 +00:00

Currently, we have 16 top-level navigation items on docs.coopcloud.tech, which might be too many (especially for screenreader users, although apparently not necessarily in general).

I wonder if it's useful to organise the docs by role?

Intro
- Architecture overview
- FAQs
App deployer (our main public)
- Deploy your first app
- App config guide (although on the way out)
- How to manage the .abra directory
- Manage secret data
- Back up and restore an app
- Scale up an app to handle more traffic
- Roll back an app to a previous version
- Running abra on the server
Recipe maintainer
- Package your first recipe (currently a section on "Recipe maintainer guide")
- Recipe reference (new)
- How recipes are versioned (currently a section on "Recipe maintainer guide")
- Understanding networking
Community member
- Contributing guide
- Community organising
- Strategy
- Bike map

Then, where to put:

Abra guide
Managed hosting
Troubleshooting

Currently, we have 16 top-level navigation items on docs.coopcloud.tech, which might be too many (especially for screenreader users, although apparently [not necessarily in general](https://uxmyths.com/post/931925744/myth-23-choices-should-always-be-limited-to-seven)). I wonder if it's useful to organise the docs by role? - Intro - Architecture overview - FAQs - App deployer (our main public) - Deploy your first app - App config guide (although on the way out) - How to manage the .abra directory - Manage secret data - Back up and restore an app - Scale up an app to handle more traffic - Roll back an app to a previous version - Running abra on the server - Recipe maintainer - Package your first recipe (currently a section on "Recipe maintainer guide") - Recipe reference (new) - How recipes are versioned (currently a section on "Recipe maintainer guide") - Understanding networking - Community member - Contributing guide - Community organising - Strategy - Bike map Then, where to put: - Abra guide - Managed hosting - Troubleshooting

👍 1

trav commented

2021-11-17 12:27:03 +00:00

Agreed, too many headings. I think of docs as specifically technical documentation. I propose other alternate headings and move a bunch to the main site. Tho maybe this isn't any better hah.

Introduction
Getting started guide
Abra guide (rename 'advanced abra' or something)

Admin guide

App catalogue

Contributing
Recipe maintainer guide
Contributing guide

Connect with us
Community organising (rename kite flying hours, link to blog from somewhere else)
Get in touch

Troubleshooting
Frequently asked questions

move off docs onto front page:
Managed Hosting
Acknowledgements
Bike map
Strategy (combine into bike map?)

dead anyway: App config guide

Agreed, too many headings. I think of docs as specifically technical documentation. I propose other alternate headings and move a bunch to the main site. Tho maybe this isn't any better hah. Introduction Getting started guide Abra guide (rename 'advanced abra' or something) Admin guide App catalogue Contributing Recipe maintainer guide Contributing guide Connect with us Community organising (rename kite flying hours, link to blog from somewhere else) Get in touch Troubleshooting Frequently asked questions move off docs onto front page: Managed Hosting Acknowledgements Bike map Strategy (combine into bike map?) dead anyway: App config guide

❤️ 1

decentral1se commented

2021-11-18 18:42:01 +00:00

Nice! I've been discussing with @simoon (not here yet) about how to organise the documentation via coop-cloud/organising#78 and last I heard, he was coming up with some visual cues and layouts to help us think through making the docs coherent for different people. Maybe we could do a collective mindmeld soon on this? Deffo wanna squash docs next.

Nice! I've been discussing with @simoon (not here yet) about how to organise the documentation via https://git.coopcloud.tech/coop-cloud/organising/issues/78 and last I heard, he was coming up with some visual cues and layouts to help us think through making the docs coherent for different people. Maybe we could do a collective mindmeld soon on this? Deffo wanna squash docs next.

3wordchant commented

2021-11-20 12:57:08 +00:00

@decentral1se yep very down for a mind-meld! 🧠

@trav I like the idea of yeeting some stuff onto the main site, and fine with most of the rest, I'd really like to see a whole section for recipe maintainers though because a) there's likely going to be a lot of content there and b) I imagine a whole group of co-op cloud users who might never need to package or update a recipe themselves.

@decentral1se yep very down for a mind-meld! 🧠 @trav I like the idea of yeeting some stuff onto the main site, and fine with most of the rest, I'd really like to see a whole section for recipe maintainers though because a) there's likely going to be a lot of content there and b) I imagine a whole group of co-op cloud users who might never need to package or update a recipe themselves.

decentral1se commented

2022-01-21 13:30:31 +00:00

New menu layout + intro page, moved other stuff into x-archive folder, i find it personally easier to work from that setup and move pages back in as i find a place in the puzzle for them. https://docs.coopcloud.tech/ hmu with feedback / thoughts or feel free to fire some commits in!

decentral1se commented

2022-01-26 10:56:01 +00:00

I've tried my best to take this thinking into the new nav setup:

https://docs.coopcloud.tech/

gonna close now, please feel free to re-open if you wanna keep discussing.

I've tried my best to take this thinking into the new nav setup: https://docs.coopcloud.tech/ gonna close now, please feel free to re-open if you wanna keep discussing.

decentral1se closed this issue

2022-01-26 10:56:01 +00:00

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/docs.coopcloud.tech#26