User docs#35
Conversation
patrickwalton
left a comment
patrickwalton
left a comment
There was a problem hiding this comment.
First off, small thing, but can you install Cursor extension "markdownlint" and address all linter errors?
I have a lot of comments. I understand it will take you time to address them, but I still think it is good we pushed to have this done sooner. Some of these you may have addressed yourself with more time, but I suspect many you would not have. This way we end up with finished docs with feedback in the same time you might have finished without.
Comments on your 01-installation.md
(since it doesn't show up in files changed)
- include the python-devel dependency next to the python dependency. (mention pip here as well instead of in later).
- Can you ask Ben to test with 0.5 on Windows? Unless you tested Windows yourself.
- Does install.sh install the python library? I think that would be a good thing. Then you could mention in the python library section
- Can you handle any of the troubleshooting steps in the install.sh? If we can do this and prev bullet, we should say that install.sh is the preferred install method and point the other methods to a section that fills in these gaps.
Editable Python install (for working on the bindings)
I'm not quite sure what working on the bindings means or whether it applies to the average user.
If Cargo is missing, the script prints how to install Rust via rustup.
Not necessary in documentation. Users can cross that bridge when they get there.
Vim syntax highlighting is not part of the script; see the README Vim support section.
Premature reference. I would just remove. User hasn't encountered Vim yet.
Vim: See the Vim support section in the main README for syntax highlighting.
if you haven't updated the vim syntax highlighter, you should mark this as not maintained and add a task to update with new grammar (maybe already is one)
Other Comments
- Do we have a way to build the docs using our own syntax highlighting for code blocks? We currently have a couple domains for oneil (oneil-lang.org, oneil.systems), but I am also trying to get oneil.org. Either way, we could host the docs at the domain.
There was a problem hiding this comment.
Can you make a graphic here that shows big font parameter and then has the descriptions of each part of the syntax below?
This is a rough idea, but of course a little too childish.
There was a problem hiding this comment.
It might be good to put that graphic in an introduction that answers one question upfront: Why should I read these docs and use Oneil?
You could seed the introduction with the intro to the original docs.
There was a problem hiding this comment.
- Parameter graphic
- Introduction: Why should I read these docs and use Oneil?
There was a problem hiding this comment.
When I wrote the first Oneil documentation, I spent some time try to write examples that would have character and start to spark ideas about what people could do with the language. In rewriting these. You have stripped the character out.
Good writing is not ascetic. Good writing has personality and makes the reader feel like they are talking to a friend or at least a human. Part of why that's true is because the purpose of technical writing is utilitarian: get more readers to learn the subject matter. Dry content discourages readers.
See if you can go back and start to build something with your models. If you can update the Oneil cylinder examples, you should do so to save time and avoid reinventing. I like the idea of building an Oneil cylinder, since it fits with the name. In the future, we could do something a little more familiar to prospective users, maybe a rocket.
There was a problem hiding this comment.
- Models should have character
patrickwalton
left a comment
patrickwalton
left a comment
There was a problem hiding this comment.
Sorry, I hit submit too early. Generally, I wanted to add that this is a really good start. Thank you.
Other comments
- The guide (in contrast to a language reference), should be written as though you're teaching a friend to use the language. One exercise you can use to see how far away you are is to rewrite paragraphs strictly in second-person. "To write a parameter, you can do x, y, z."
There was a problem hiding this comment.
I like how concise this one is, but it could maybe use a couple more examples.
I also think it's showing up too early. For example, the user hasn't been introduced to units yet.
There was a problem hiding this comment.
You're right, I forgot that units hadn't been introduced yet. I introduced tests early so that they could be used in later chapters without confusing the user.
- Add more examples
We don't currently have a way, but I don't think it would be hard to implement one. There are plenty of syntax highlighting libraries out there (see highlight.js, bright, and pygments). All we'd have to do is describe the grammar in a way that the library understands and it will fill in the rest. |
|
I've gone through and added tasks to each piece of feedback. If you have any updates to the tasks feel free to comment them. I've also marked comments that contain questions/need feedback with ' 😕 '. |
|
K, I believe I've addressed all of your questions. |
- Fix 09-importing-models.md: replace old Python keywords (ref/use) with Rust keywords (reference/submodel); add `[alias]` extraction section with realistic constants/planet examples - Remove "not supported yet" stub in 01-overview.md; replace with a brief designs overview and link to the new chapter - Add 10-designs.md + examples covering design files fix: correct parameter.alias ordering (parameter first, alias second) Made-with: Cursor docs: replace environment/spacecraft with extraction example with solar-system/galaxy Co-authored-by: Cursor <cursoragent@cursor.com> docs: replace extract/extraction terminology with alias/aliasing framing Co-authored-by: Cursor <cursoragent@cursor.com> docs: add runnable examples and real output to designs chapter - Add docs/guide/examples/10-designs/ with 19 .on/.one example files covering every section of the chapter - Fill in all oneil-eval-output blocks with actual compiler output - Fix derived_planet.one: add explicit :km^2 unit on surface_area - Fix cycle_test.on: add comment header to avoid span-tracking crash on very small files (22-byte edge case) - Add moon.on + moon_design.one for the target-mismatch error case; replace TODO stub with real error message from the compiler - Sync 09-importing-models.md with user's manual section-heading edit Co-authored-by: Cursor <cursoragent@cursor.com> docs: update highlighter and overview for new import/design keywords highlight.js: - Replace `use` rule with `submodel` (drop `with` keyword, keep [alias] block) - Replace `ref` rule with `reference` - Add `design` declaration rule - Add `apply` declaration rule with `to` as a keyword 01-overview.md Model imports section: - Replace `use` with `submodel`, `ref` with `reference` in code blocks - Fix `load_max.b` → `load_max.battery` (no alias was declared for battery) - Update prose descriptions to match new keyword names Co-authored-by: Cursor <cursoragent@cursor.com>
Revise importing-models and designs chapters to read more like a
tutorial than a reference — second-person framing, personality in the
prose, examples that motivate before they demonstrate.
Key changes:
- Replace formal constructions ("to this end", semicolon definitions)
with direct second-person phrasing throughout
- Move the parameter-access rationale note to after the example
- Update the submodel parameter example to demonstrate both single-
and multi-level dotted overrides, with a recommendation to use a
dedicated design when overriding multiple parameters
- Replace passive error sentences with active "you'll get an error"
phrasing
- Replace "instance" (programmer jargon) with "model" throughout
- Fix "filename" → "model name" for the default alias behaviour
- Correct the multi-level dotted syntax example to the right order
(parameter.parent.child, not parameter.child.parent)
| # boosted_mission.one | ||
| design mission | ||
|
|
||
| thrust.vehicle.main_engine = 2000 :N |
There was a problem hiding this comment.
This is what I was talking about. We are designing mission, it has a spacecraft submodel we call vehicle, and that vehicle has a main_engine which has a thrust.
Alternatives:
thrust.vehicle.main_engineis weird because it is the thrust of the main_engine, not the whole vehicle.thrust.main_engine.vehicleseems strange at least to programmers and english readers since to verify that the parameter is accessible you have to read from right to left to make sure you used valid submodel names / references.
At one point early on I think we discussed that we should disallow nested . even for designs, but later I remember you wanting it. Since we can't add [main_engine] to the submodel in mission from the design file, we don't currently have any other way of modifying thrust other than creating a design for spacecraft and applying it to vehicle (alternative 3).
In other words, we either need to provide a justification for one of the first two alternatives or make clear that nested access to parameters is disallowed and applying designs should be used instead.
I remember you saying that we should support nesting because designs are too much overhead for a single parameter change.
3 participants
Update the user docs and the README quick start.
Also has an unrelated addition of displaying test references in trees. I can move that commit to a seperate PR if you have a lot of questions about it. Basically, tests now are displayed as dependents alongside other parameters.