mastodon / mastodon/documentation

[Client guide] Extend/rework the user journey with "feature overview" pages

Open
#1,898 0 comments 0 reactions 0 assignees View on GitHub

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:

  • apps is first because you need to register your client.
    • oauth is nested under that because you will probably need to obtain tokens for your client or anyone using your client.
  • accounts was 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, etc
  • statuses for when your users were ready to start posting
    • media attachments, polls, and scheduled_statuses are likely to be used while posting
  • timelines for when your users want to view multiple statuses
    • lists, markers, streaming were also relevant when working with timelines
  • notifications as the next thing to deal with
    • push notifications being a subset of that
  • search as the last remaining thing a user might do
  • instance for anyone wanting to get info about the instance itself
    • trends and the profile directory were also instance-wide features, etc
  • admin for 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.