Hacker News Reader

Comment by skybrian | Hacker News Reader

It sounds like you know what you’re doing but the documentation seems rather shallow and I don’t quite get it. I think you’re going to need a real language specification. I like how Go does it.

There is some apparently AI-generated prose that needs rewriting for clarity. For example, in the tutorial:

> The caller proves where; the implementation proves ensures. A precondition failure stops compilation before any program runs.

Fron the readme:

> I think you get it now.

Nope, I skimmed, because the syntax is unfamiliar.

> Memory model is in a tree of "planes". The stack is a tree. Each function is a node. Each variable is another node. If it's a struct then it's also a node. Down to the most atomic types, which are just the integers.

Meaning what? This needs to be explained better.

View on HN

Yeah the repo/documentation is pretty rough right now. TBH I am not quite ready to spend a ton of time on docs yet as some of these things are changing on the fly. But the core concept/syntax should remain the same. The code is not super interesting yet, though

Yeah, if I were motivated I’m sure I could figure it out from the tutorial.

And, to be clear, the README was mostly an initial prompt for the AI. I’ll prioritize making a much clearer and legible README soon

A good tip is to actually polish your README before sharing it with everyone.

I considered waiting longer to share more but felt feedback early was better than waiting for more polish. Will focus on this with high priority though, good feedback

I think you might want to more deeply consider the impact it has on people when you ask them to read a bunch of LLM-generated code and documentation that you haven't even taken the time to "polish" yet. Some (myself included) might consider it a violation of an implicit social contract to expect such disproportionate effort from your audience than you are willing to spend yourself upfront.

Maybe, to put it another way: Why should people want to spend time developing feedback for you when you were not willing to spend commensurate time on the things you want to show them first? You're putting the cart before the horse.

I agree with you, if I were asking for a code review. I'm mostly interested in what people think of the language features. A code review in its current state is not interesting, but I believe the site has some ideas that can be food-for-thought

If you want to have an LLM write your README (and other docs), I've found it useful to add a DOCS-GUIDE.md to your project and write your conventions and expectations there.

Google has a two-part technical writing crash course:

  - https://developers.google.com/tech-writing/one
  - https://developers.google.com/tech-writing/two

I've had good success with adding a directive to the guide that points to those two URLs and tells the agent to adhere to them in all of its documentation.

> TBH I am not quite ready to spend a ton of time on docs yet as some of these things are changing on the fly.

I'd assume, what you do is based on some research, with articles and other projects like yours - these references are what's missing from your project, you don't have to write them yourself.

The most important missing explanation, that only you can provide, is this: Why a new language? There are projects that attach proof obligations to standard Rust in order to reuse its vast ecosystem and existing LLM skills. That would be a far easier and more productive approach to take.

For me part of the fun of such a side project is complete control. I’m willing to risk this over starting from something existing, which may be the wrong call!

congrats & just fyi, you should put a "Show HN" if you are posting and presenting your own handiwork. Better optics.

Just want to say that you did a great job giving critique. Felt encouraging even though it's not even my project

Reply on news.ycombinator.com