Improvements to Swift-DocC README file

Hello everyone! - I’d like to propose a change to the README file in the Swift-DocC GitHub repo that aims to improve the clarity and conciseness of the documentation about DocC.

Motivation

Currently, when searching for the terms “DocC” or “DocC Swift” on web browsers, the Swift-DocC GitHub repo is among the first search results listed, thus inferring that it has relevance and that there’s a big possibility that users who want to start using DocC relies on the GitHub README file to understand how to get started with the tool.

The problem with the current structure of the README is that it is not concise, providing too much technical information on how the project is structured but not on how to start using the tool. The only instructions provided on how to get started with DocC are specific to the user who wants to get started making open-source contributions, which from what has been noticed, leads to confusion from people thinking that this is the go-to way to use DocC for generating documentation.

Proposed Change

To improve the user experience for users trying to get started with DocC I propose some changes to the README file of the Swift-DocC repo. This change simplifies the information regarding the steps needed to get the tool working depending on the identified use cases:

  1. For standalone documentation
  2. For documenting packages via SwiftPM
  3. For documenting apps and frameworks using Xcode

These changes were made trying to only give key information on the tool and linking to the official external resources as the DocC docs inside Swift Org and Apple Developer Documentation, not repeating information that’s already explained in these other resources and not transforming the README into another documentation website about DocC.

The technical explanation about the project and how to set up the tool to start making open-source contributions was moved to the CONTRIBUTING file, decluttering the README and leaving only important information about getting started, reporting bugs, and requesting new features.


I believe that starting with small UX improvements like this can lead to big wins for the tool :smile:

The proposed change is currently open as a PR and I would like to know your thoughts about it, either as general feedback in this post or directly in the PR. I’m looking forward to know your thought about this.

Thanks!

9 Likes

I love how your changes in the PR distinguish usage (README.md) from contributing.md. I feel that it's a good idea to clean up the README and bring more clarity for newcomers like myself.

I agree with @Joseph_Heck that perhaps SwiftPM plugin is a more common use case than trying to use docc directly.

The big thing for me when I was re-reading documentation was to understand that there's a separate DocC documentation site for using DocC to author docs, and a separate DocC site describing how DocC itself works. They're both linked to in README, but it wasn't all that clear to me until I really stopped to re-read it carefully.

2 Likes