There are docs resources like https://diataxis.fr/ that categorise documents based on format and intended audience.
They don't say where you should start, or what order you should write docs.
I'm currently thinking README > reference > tutorial > how-tos. Agree/disagree?
miniblog.
I'm still tinkering with the website for my PL experiment. I want the styling to express "labour of love hobby project".
Choosing what program to show on the home page is really hard too. All the keywords are links like Racket.
What do you think? https://www.garden-lang.org/
I regularly see the phrase "all Xs are Ys, but not all Ys are Xs" in teaching material. Even material for children!
I have to re-read it every time. I very much prefer "Y is a more general category than X" or "X is a subset of Y".
Do people find this phrasing helpful, or is it poor pedagogy?
Over a sufficiently long time horizon, all code you write is legacy code.
I've written difftastic packaging instructions: https://difftastic.wilfred.me.uk/packaging_difftastic.html
The different distros have taken different approaches, so I'm trying to help with common gotchas — don't forget the man page!
Feedback welcome, especially if you've ever packaged something 🙂
The "line of death", where the browser UI splits between trusted UI elements and UI controlled by the website.
Also argues that HTTP warnings are better than HTTPS padlocks, because there's incentive to spoof padlocks lower on the page.
https://emilymstark.com/2022/12/18/death-to-the-line-of-death.html
Further tinkering with diagnostics, following feedback!
* Two lines of context above and below now.
* The caret is included in the line below where possible.
* Syntax highlighting of keywords.
I kinda feel that smart context sizing would be better. What do you think so far?
I'm experimenting with diagnostics formatting.
* I've added a left margin, showing both the file name and line numbers
* I'm showing one line of context above/below the offending line.
* I'm using grey for comments.
What do you think? Is there anything you'd change?
Trying the nix CLI today, and I'm seriously impressed with the formatting of its --help output.
Indented warnings, italics, bullets, even adding a left border to code snippets! It's a nice reminder to take full advantage of terminal features to help the reader.
I've heard of 'blub languages', where you don't realise that other languages have better abstractions until you've experienced them.
I think the same thing happens with individual features. I've seen several C++ folks miss variadic generics in Rust, but I've not written enough C++ to feel it.
Designing UIs is such a hard problem.
Sometimes I try a bunch of options and I settle on "this one seems the least annoying".
I'm not sure if I should use the term "text diff" or "textual diff" to refer to a conventional, line-oriented diff of text in difftastic.
Any opinions? Which seems clearer to you?
I frequently find myself running:
$ slowish
$ slowish | jq
$ slowish | jq | grep
I feel there must be a better way to build up pipelines incrementally without re-running.
I could save each output to a file, but it's more verbose, and most of these tools have nicer output when stdout is a TTY.
There are *so many* ways that reading a text file can fail.
Maybe it doesn't exist, it's a broken symlink, it's actually a directory, it's not the encoding you expected, or perhaps you just don't have the correct permissions.
Reporting good errors is surprisingly labour intensive.
When writing long-lived programs (daemons etc) in Rust, I find myself asking *where* I should put data.
In a GC'd language it's just "I have a string" but Rust forces me to find somewhere to put it.
You do get a performance benefit for this work though.
On the challenge of writing accurate source spans on Unicode source code: https://reedmullanix.com/posts/unicode-source-spans.html
Also (see footnotes) a fair number of LSP clients assume UTF-8 despite early versions of LSP mandating UTF-16!
I'm trying to decide the best voice for PL documentation.
Passive: "`let` can be used with destructuring."
Reader focused: "You can use `let` with destructuring."
Describing the PL: "FooLang supports destructuring with `let`."
Anyone have opinions or best practices?
I'm coming round to the view that a main function shouldn't take arguments.
For example, in Rust you have to call std::env::args() to get CLI arguments.
This makes Hello World less verbose, and gives you more flexibility in setting up CLI argument parsers.
The word "agent" is so overloaded in the AI space.
Sometimes it means a sophisticated interaction system, but other times it just means API.
I think it's partly a sign of how new the space is. We don't have consensus on the best way to use these systems yet.
I've seen "cons cells" and "cons pairs", but today I saw "conses", which is new to me.
(Clearly Lisp has no downsides, only pros and cons! 🙃)
Showing 61-80 of 7,506 posts