mastodon / mastodon/documentation
[Client guide] Extend/rework the user journey with "feature overview" pages
Nobody has claimed this yet.
- Dominant language
- SCSS
- Stars
- 1.7k
- Forks
- 978
- PR merge metrics
- No merged PRs in 30d
Description
https://github.com/mastodon/documentation/pull/1896 alphabetizes a previously mostly-structured menu for the API methods, which is a fine change for purely reference-based workflows, but it would be nice to have that old structure preserved somewhere else.
The current (old) ordering sorta follows a journey of how you might want to implement certain API features. I think it could be handled by reworking the /client/ ("Developing Mastodon apps") section to include "feature" pages, but I never got around to that.
So for example:
appsis first because you need to register your client.
oauthis nested under that because you will probably need to obtain tokens for your client or anyone using your client.accountswas second because once your client has users, it makes sense to register accounts, verify credentials, browse profiles, etc.
- Various API routes related to your account are nested under that --
bookmarks,favourites,mutes,blocks,filters, etcstatusesfor when your users were ready to start posting
mediaattachments,polls, andscheduled_statusesare likely to be used while postingtimelinesfor when your users want to view multiple statuses
lists,markers,streamingwere also relevant when working with timelinesnotificationsas the next thing to deal with
pushnotifications being a subset of thatsearchas the last remaining thing a user might doinstancefor anyone wanting to get info about the instance itself
trendsand theprofiledirectory were also instance-wide features, etcadminfor all the admin stuff which most users wouldn't need to use
- all the stuff prefixed with admin/
If you look at the end of a page like https://docs.joinmastodon.org/client/authorized/ you can see a sort-of skeleton of the same rough concept that never got expanded on. It could be worthwhile to expand this out from a list into "feature" pages just like what was done with quote posts. So you'd have the existing "public" -> "authorized client" -> "authorized user" journey, but extend it with a feature-by-feature breakdown.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the /client/ “Developing Mastodon apps” section, the navigation skeleton at /client/authorized/, and PR 1896’s menu changes. Map the proposed feature pages and their journey from public access through authorized clients and users. Done means the client guide preserves that journey with feature-by-feature pages and navigation.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100