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

Add guide to using Rednet #1647

Open
wants to merge 3 commits into
base: mc-1.20.x
Choose a base branch
from

Conversation

MCJack123
Copy link
Contributor

This PR adds a guide for using Rednet, describing setup, sending and receiving messages, using protocols, using host lookup, and security suggestions + usage info.

The security section may be too dense even for people interested - maybe it's better to be split off somewhere else? It also mentions third-party projects, which I don't know whether you'd want that on the website. Otherwise, this should be a pretty comprehensive tutorial.

@Lupus590
Copy link
Contributor

Lupus590 commented Dec 5, 2023

I feel like encryption (if included at all) should be its own page.

Copy link
Member

@SquidDev SquidDev left a comment

Choose a reason for hiding this comment

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

Thank you for working on this!

I think the content here is pretty good, but I'm not sure the structure is quite there right now. The order the information is presented is a bit odd - for instance, we're talking about sending files or tables, before the reader has even received a basic string!

My general approach to these sorts of docs is to tell a sort of story. We introduce a simple idea and let the reader use it. Then in the next section, we highlight a deficiency and/or possible extension, and use that as a motivation for introducing the next idea.

I'm taking some inspiration from the diataxis model for tutorials here, though I'm definitely not disciplined enough to follow it to the letter.

I really like the turtle control program, and think that might be a good example to develop throughout the tutorial. Using that, we we could split the guide into several steps the reader can follow:

  1. Setting up a modem and calling rednet.open on a single computer.
  2. Setting up a turtle with a modem, and sending messages to the turtle.
  3. Introduce a basic turtle control program. Don't introduce any new ideas here, but just the basic program.
  4. Then use that as a motivation for other features. For instance:
    • Using tables to send the result back to the controlling computer.
    • Protocols and host lookup for selecting which turtle to control.
    • Broadcast to control multiple turtles at once.

Mostly using this structure as an example to explain what I'm trying to do. Definitely don't feel like you have to follow this at all!

I think the cryptography section needs to be in an entirely different document. Someone just starting with rednet doesn't need to know that "Curve25519 is an elliptic curve asymmetric cryptographic algorithm" :p.

# Transferring information wirelessly using Rednet
Being able to send data between computers is an important feature for various
programs, including turtle controllers and distributed banking systems.
[modem](https://tweaked.cc/peripheral/modem.html) peripheral enables computers
Copy link
Member

Choose a reason for hiding this comment

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

We use the same markdown processor as the rest of the docs, so it should be possible to use [`modem`] here instead.

@SquidDev SquidDev added enhancement An extension of a feature or a new feature. area-Documentation Improving/fixing documentation labels Dec 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-Documentation Improving/fixing documentation enhancement An extension of a feature or a new feature.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants