Skip to content

Standardize README See also section formatting #44

Description

@Ununp3ntium115

Standardize README "See also" Section Formatting

Problem Summary

The "See also" section in README.md has inconsistent formatting. Some entries are just URLs, while the newly added Rust driver entry includes a description in parentheses. This inconsistency should be standardized for better readability and maintainability.

Current State

Location: README.md, lines 22-30

Current Format:

## See also

* https://github.com/Ableton/push2-display-with-juce                      
* https://github.com/Deep-Symmetry/wayang
* https://www.npmjs.com/package/ableton-push2
* https://github.com/net147/Push2Qml
* http://sigabort.co/p2d
* https://github.com/garrensmith/abletonpush
* https://github.com/wookay/PushInterface.jl
* https://github.com/ffont/push2-python
* https://crates.io/crates/push2_display (Rust display driver)

Issues:

  • Most entries are just URLs
  • Rust entry has description: (Rust display driver)
  • Inconsistent formatting makes it harder to scan
  • Some entries have trailing whitespace

Impact

  • Priority: Low (cosmetic/documentation improvement)
  • User Experience: Inconsistent formatting is less professional
  • Maintainability: Harder to maintain consistent format when adding new entries

Proposed Solutions

Option 1: Remove Description (Match Existing Format)

Remove the description from the Rust entry to match the existing format:

--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Please add an [issue](https://github.com/Ableton/push-interface/issues) with you
 * https://github.com/garrensmith/abletonpush
 * https://github.com/wookay/PushInterface.jl
 * https://github.com/ffont/push2-python
-* https://crates.io/crates/push2_display (Rust display driver)
+* https://crates.io/crates/push2_display
 
   Please Note: The external links are being provided as a convenience and for informational purposes only.

Option 2: Add Descriptions to All Entries (More Informative)

Add descriptions to all entries for consistency and better user experience:

--- a/README.md
+++ b/README.md
@@ -20,15 +20,15 @@ Please add an [issue](https://github.com/Ableton/push-interface/issues) with you
 ## See also
 
-* https://github.com/Ableton/push2-display-with-juce                      
-* https://github.com/Deep-Symmetry/wayang
-* https://www.npmjs.com/package/ableton-push2
-* https://github.com/net147/Push2Qml
-* http://sigabort.co/p2d
-* https://github.com/garrensmith/abletonpush
-* https://github.com/wookay/PushInterface.jl
-* https://github.com/ffont/push2-python
-* https://crates.io/crates/push2_display (Rust display driver)
+* https://github.com/Ableton/push2-display-with-juce (JUCE display driver)
+* https://github.com/Deep-Symmetry/wayang (Clojure library)
+* https://www.npmjs.com/package/ableton-push2 (Node.js package)
+* https://github.com/net147/Push2Qml (QML implementation)
+* http://sigabort.co/p2d (Display driver)
+* https://github.com/garrensmith/abletonpush (Python library)
+* https://github.com/wookay/PushInterface.jl (Julia package)
+* https://github.com/ffont/push2-python (Python library)
+* https://crates.io/crates/push2_display (Rust display driver)
 
   Please Note: The external links are being provided as a convenience and for informational purposes only.

Option 3: Organize by Category (Most Structured)

Group entries by type (GitHub repos, npm packages, crates.io, etc.):

--- a/README.md
+++ b/README.md
@@ -20,15 +20,20 @@ Please add an [issue](https://github.com/Ableton/push-interface/issues) with you
 ## See also
 
-* https://github.com/Ableton/push2-display-with-juce                      
-* https://github.com/Deep-Symmetry/wayang
-* https://www.npmjs.com/package/ableton-push2
-* https://github.com/net147/Push2Qml
-* http://sigabort.co/p2d
-* https://github.com/garrensmith/abletonpush
-* https://github.com/wookay/PushInterface.jl
-* https://github.com/ffont/push2-python
-* https://crates.io/crates/push2_display (Rust display driver)
+### GitHub Repositories
+* https://github.com/Ableton/push2-display-with-juce
+* https://github.com/Deep-Symmetry/wayang
+* https://github.com/net147/Push2Qml
+* https://github.com/garrensmith/abletonpush
+* https://github.com/wookay/PushInterface.jl
+* https://github.com/ffont/push2-python
+
+### Package Registries
+* https://www.npmjs.com/package/ableton-push2 (Node.js)
+* https://crates.io/crates/push2_display (Rust)
+
+### Other
+* http://sigabort.co/p2d

Recommendation

Option 1 is recommended because:

  • Minimal change
  • Matches existing format
  • Easy to implement
  • Low risk

Option 2 would be better long-term but requires:

  • Research to determine accurate descriptions for all entries
  • More maintenance when adding new entries
  • May need to verify descriptions with maintainers

Option 3 is most structured but:

  • Requires more significant restructuring
  • May be overkill for current number of entries

Verification Steps

  1. Choose which option to implement
  2. Verify all links still work after changes
  3. Check formatting consistency
  4. Remove any trailing whitespace

Additional Notes

  • This is a cosmetic improvement
  • Option 1 is the safest and quickest fix
  • Consider Option 2 or 3 for future if the list grows significantly
  • All options maintain the disclaimer note at the bottom

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions