Skip to content
New issue

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

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

Already on GitHub? # to your account

docs: create suggestions for book improvement #263

Closed
wants to merge 3 commits into from

Conversation

od-hunter
Copy link

Issue: Close #259

Description

The changes here is just a draft PR to find out from the maintainers if my implementation is inline with the project description

Copy link
Member

@julio4 julio4 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say it's not bad but don't create a new md file for the changes, either:

  • Directly apply the change in the PR and comment the change on github directly
  • First propose the change on github and we can discuss it

And if you use AI tools please be sure to verify by yourself all the suggestions as well!

@od-hunter
Copy link
Author

@julio4, thank you for your input could you kindly confirm if the approach I used in the last two PRs aligns with your recommendation to make and comment the changes directly here?

Commit 53800b5: Fixed the broken contribute link across multiple pages in the book. It previously pointed to a 404 page, but I changed it to point to the CONTRIBUTING.md file.

Commit 9ca6616: Fixed another broken link.

Does this approach align with your suggestion in your previous comment?

I would say it's not bad but don't create a new md file for the changes, either:

  • Directly apply the change in the PR and comment the change on github directly
  • First propose the change on github and we can discuss it

And if you use AI tools please be sure to verify by yourself all the suggestions as well!

@od-hunter
Copy link
Author

od-hunter commented Nov 29, 2024

@julio4,

I'm proposing a suggestion to enhance the user experience for first-time users of this book. Since the main contract code, interfaces, and tests are stored in listings, while the main contract and interface definitions might not be immediately visible to users unfamiliar with the book's structure, I suggest adding a link tag to the location of the visible code in the listings.

Example:

Specifically, I propose modifying the current implementation:

Current:

// [!include ~/listings/getting-started/counter/src/counter.cairo:contract]

Suggested:

// [!include ~/listings/getting-started/counter/src/counter.cairo:contract]
To run the contract, visit: [Simple Counter](https://github.com/NethermindEth/StarknetByExample/blob/dev/listings/getting-started/counter/src/counter.cairo)

This change would provide easier access to the full contract code for users who want to explore the implementation and interface definitions.

Additionally, I suggest introducing this approach throughout the book wherever necessary. For example, we could add similar links at the beginning of each chapter or section that includes listings, providing easy access to the complete source code.

@od-hunter od-hunter marked this pull request as ready for review November 29, 2024 16:32
@julio4 julio4 closed this Jan 26, 2025
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Feat: Book Proofread
2 participants