Document how to use startup files #1069
Conversation
|
Thanks for putting this together! I wonder if it's worth leaving off the section on case sensitivity, and just saying "keep it lower case". It's good content to have, but probably better off in the main |
SquidDev
added
enhancement
there's a few more but these are the ones that I think are good changes
There was a problem hiding this comment.
Thank you very much for putting this together! I always forget how terribly even the core bits of functionality are documented.
I think the content is good here, I'm just quite sure about the structure yet. What I'm trying to do with guides1 is provide something which is relatively incremental - users can follow along, stop at any point, but still have something actionable they can take away from it.
I think right now things are a little confusing because so much is introduced in one go at the beginning, and it's not clear what 'I' can/should do2. I think I'd propose splitting the docs into several sections like so:
-
startup.lua: Motivation (run program when a computer turns on) and a basic example: "create a
startup.luafile and run the reboot program". We have some funky support for mounting code snippets on computers3, so you could have two snippets here: one with the startup file and another just saying "Press the run button to see the startup file in action". -
startup directory: Talk about
startupvsstartup.luaand thestartup/directory. We could even have another snippet here, talking about creating astartup/another-startup.luafile, mount that along with the previous startup file, and demo it again. -
Starting from disks: Move that "Mass configuration" section to the top (though leave out the stuff on settings for now)! This is a great "why would I want to do this?".
We can't really demo this in-browser, but can still explain how you'd do this (i.e. move your startup.lua and startup/ files onto a disk and reboot).
At the end of this section it's probably worth talking about what happens when you've got multiple drives.
-
Settings: Mention the two
shell.*settings. Possibly anything else you think is relevant?
Footnotes
-
And to be clear, I'm not sure I've been successful yet, even in the stuff I wrote!
Really I should be following something more structured like the Diataxis Framework, but I really struggle writing in a way which doesn't end up being three kinds of topic in one. Though I probably should move the Lua 5.2/5.3 compatibility stuff into a "Reference" section at least. ↩
-
As always, I'm the worst person to be commenting on docs, because I don't know what beginners need. ↩
-
Worth noting the example runner will override a startup.lua file, but that should be easy to fix - just swap these two elements. Not sure if you've got CC:T's full build environment (and illuaminate) set up locally, so happy to do that bit if you'd prefer. ↩
- Add a TOC to the Local IPs page. - Increase the echo delay in our speaker audio page to 1.5s. This sounds much better and is less clashy than 1s. Also add a sleep(0) (eww, I know) to fix timeouts on some browsers/computers. - Move Lua feature compat to a new "reference" section. Still haven't figured out how to structure these docs - open to any ideas really. - Mention FFmpeg as an option for converting to DFPWM (closes #1075). - Allow data-mount to override built-in files. See my comment in #1069.
Co-authored-by: Jonathan Coates <git@squiddev.cc>
SquidDev
changed the title
I'm fairly sure that I don't, the proper build steps break before doc gen so I've been calling that manually and it's not produced quite how I expect it to. Some CSS or markdown-to-html might not be working. I wouldn't mind pointers, can do it via discord if it's easier. Edit: thanks |
…into docs/startup_files
…into docs/startup_files
…into docs/startup_files
off topic change
…into docs/startup_files
Related: #1068