Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance Swift Numerics README.md (technical writing perspective) #1

Merged
merged 1 commit into from
Sep 2, 2020
Merged

Conversation

8bitmp3
Copy link

@8bitmp3 8bitmp3 commented Sep 2, 2020

Hey @markuswntr!

I've looked at your Swift Numerics PR (ApproximateEquality): apple#150 and thought we could bundle a few changes together.

I've made a few improvement suggestions to the entire README based on tech writing experience - hope you like them:

  • Small change: "may migrate in the second" -> "may migrate into the second"
  • Refactor: "new uses are discovered" (passive voice) -> "more users start using Swift Numerics." (active voice)
  • Reduce the use of "simply" if possible (it's not necessary but is recommended)
  • Refactor + replace the idiom ("to pull in") for internalization/inclusiveness:
- Swift Numerics modules are fine-grained; if you need support for Complex
+ Swift Numerics modules are fine-grained. For example, if you need support for
+ Complex numbers ...
- ... import ComplexModule¹ without pulling in everything else in the library:
+ ... import ComplexModule¹ as a standalone module:
...
- as well.
...
[Example in code blocks]
  • Refactor:
- // All swift-numerics API is now available
+ // The entire `swift-numerics` API is now available
  • Replace the use of "we" with "the Swift Numerics project". For example:
- Because we intend to make it possible to adopt Swift Numerics modules in the
- standard library at some future point...
+ The Swift Numerics project is intended to be adopted in the standard library
+ in future. Therefore, it...
  • Provide three steps (1... 2... 3...) for the Using Swift Numerics in your project section, since it's a sequential process - this helps with UX
  • Small refactor: add "that is"
- Swift Numerics is a standalone library separate from the core Swift project. In
+ Swift Numerics is a standalone library that is separate from the core Swift project. In
  • Enhance several HowTo sections under "Contributing..." into discoverable subheadings (e.g. "to propose a new module" -> "# How to propose a new module")
  • Add a "### Forums" section for improved discoverability
  • Add "About" to enhance explanations of the links:
1. About [`RealModule`](Sources/RealModule/README.md)
    - [`ApproximateEquality`](Sources/RealModule/ApproximateEquality.swift)
2. About [`ComplexModule`](Sources/ComplexModule/README.md)
  • Reformat the Markdown text to wrap at 80 characters (it's a good practice, just like in code)
  • Turn complex sentences -> smaller easier to follow sentences
  • Use second person ("you") instead of first person ("I", "we"), if you can
  • Add blank lines between the section titles and first paragraphs
  • Add blank lines between before and after code blocks

Let me know what you think.

Cheers!

@markuswntr
Copy link
Owner

@8bitmp3 I am happy to merge your changes so we can discuss your suggestions within apple#150.
Thank you!

@markuswntr markuswntr merged commit 82b04be into markuswntr:master Sep 2, 2020
@8bitmp3 8bitmp3 deleted the patch-1 branch September 2, 2020 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants