dart-lang / dart-lang/pub-dev

Add "Table of Content" to the Readme tab

Open
#4,371 13 comments 7 reactions 0 assignees View on GitHub
Type: enhancement
Dominant language
Dart
Stars
944
Forks
184
Avg merge
1d 15h
Merged PRs (30d)
12

Description

In a recent user study, participants searched within a package's documentation to find a specific feature (e.g., Ctrl+F to search “highlight” within the documentation of “markdown” package). They usually did this when they failed to find useful information after quickly scanning the documentation. They also tried multiple keywords to make sure that they didn't miss any information (e.g., “highlight”, “syntax”, “code”). It showed that search was an easy way to find information from large data, but it could be difficult to find a good keyword.

But when the feature of interest was listed under “Features” section, users didn’t have to search again. It suggests that a standardized Readme format with better navigation UI (e.g., table of contents) might save some time for participants.

We can consider adding table of contents that's similar to the one on [Go's package site](https://golang.org/pkg/os/):

![image](https://user-images.githubusercontent.com/11873270/102841896-9fdd7180-43ba-11eb-826b-57ade253a700.png)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.