https://www.boundaryml.com logo
Powered by
@Vaibhav (BAML 🐑) - was going through
# suggestions
m
@Vaibhav (BAML 🐑) - was going through the BAML repo and noticed you've got a diataxis ruleset. I've seen much better docs by splitting the rules and creating focused command files for specific types of docs. For me that means how-to and reference docs. I use the "how to" if I'm using the LLM to build a pipeline. I find that it saves me from reasoning through the code to get things started.
p
Hey there, would love to know how you apply this in practice
Do you apply these in your projects that use BAML? Is it a complex application or a throwaway workflow?
From what you're saying, it's almost like a "docs-skill.md" ruleset where each kind of diataxis doc can be written depending on what's been added, for e.g., a brand new feature vs. a small incremental change to a parameter
v
we actually have some new docs in progress that is a bit more focused on this! @rossir.paulo (BAML) will share a link when he's got one (may take a bit since he's out of vacation). can get some early feedback from yall. I wonder if there's specifics we can do to make agentic coding better for yall!
if yall wanna take a look and give some initial feedback: https://learn-baml-phi.vercel.app/ (note its very early)
(and not yet comprehensive)
p
Very cool, and seems super useful! Is this based on your diataxis markdown instruction file? Or did you rework that file to do it in smaller parts? The entire setup looks very "diataxis-y", which is awesome for learning!
h
I see WASM BAML 👀
m
Yes to all of that, haha. I'll use it on throwaways to create "how to" docs to speed up my reasoning through code. On complex docs, I'll use both "how to" and "research" incrementally. I typically start with the data model, so use "research" incrementally to keep up-to-date as the model grows. I've not had great results with the skill use so tend to send the command more deliberately
This is fantastic! my first thoughts in the "UX" department I've found on-screen prompting helps a bunch with UX. The issue is we never know where to look on the screen, exactly, so using a sprite or other callout on first load does wonders for lowering cortisol. Animating the text after 'run' will also give people's brains a chance to process and add some 'liveness' to the experience. Can also be a 'first-run' thing or a 'second click prints immediately' thing or 'every other click prints immediately' thing. What's always fascinated me about devs, generally speaking, is that everyone says "code should document itself" but then everyone talks about how hard it is to reason through code... The general rule of thumb is "5 +/- 2" to estimate the number of items a person can hold in short term memory/attention. Also, everyone has limited "decision juice" (that's the official term) so later in the day people's ability to decide will be stunted. (that's why nobody cares where you go for dinner, btw) On the more complex examples, adding a stepwise UX can help reduce cognitive load. For example, the union type has 4 classes with 7 types total (that's an ass-load of combinations) So the person is not quite sure where to look to 'map'. Highlighting the words can help (brains match colors super fast which is why Toyota uses colors in their Kanban boards and tickets) Try it yourself, on the Union type put NeedsMoreInfo into the search box and see how much faster you can find what you're loooking for. {{ General comment: the height is a bit off so I've got to scroll to get to buttons. I'm sure you're aware but it can be easy to scroll when you're coding a site and forget users don't like it)
The colors will really help on the 
@description
example. My eyes were darting back and forth and it took me a little bit to anchor on the page to find my place + think through what I'm looking at.
v
wasm BAML is coming hopefully 🙂
h
I’m eagerly waiting
PreviousNext
Powered by