Skip to content

Standardize README See also section formatting #44

@Ununp3ntium115

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

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