🆕 blog! “Can you follow your own getting started guide?”
I was trying to install a new open source project and was having a hell of a time. Nothing seemed to be working despite me following the tutorial to the letter. I was getting the most bizarre error messages and was on the verge of quitting to become a goat farmer, when I threw one […]
Secure a place in history. Create the source material for hundreds of journalists, bloggers and shitposters writing about the downfall of reddit and the rise of the threadiverse. (also missing!)...
Do you work with #voice or #speech#data? You might contribute data, write data specifications for collection, perform filtering or pre-processing, train #ASR or #TTS models, or design or perform evaluations on #ML speech models.
If so, I’d love your help to understand current #dataset#documentation practices, and what we can do to make them better as part of my #PhD#research
The #survey takes 10-20 minutes to complete, and you can opt in to win one of 3 gift cards valued at $AUD 50 each.
Research Protocol 2021/427 approved by #ANU Human Research Ethics Committee
📗 The dated Lucida Grande was the Mac system font a decade ago and used for the docs on Mac (and only Mac). We now use the system font stack, to get a similar result to Linux, Windows, Android and iOS. https://systemfontstack.com
Suppose I was thinking about writing #manpages for the command-line tools I build, but I don’t want to learn a 50 year old typesetting language (#troff) to do that.
What are my options? #Asciidoc? What would you use? What do you use?
I looked into #Pandoc Markdown to man conversion, and it seemed to suck.
A young developer who never used Windows 98 back in the day stumbled upon an introductory book on the operating system and posted his impressions on skimming it, which brought him joy. He wrote:
"I was also left with the impression that perhaps I would like more software to come with a physical manual."
As a text-first boomer I completely agree screenshots and videos are no substitute for written documentation. The mileage of younger generations may vary.
"When you throw a screenshot out into Notion (Wiki, Confluence, et cetera), you’re effectively defining a word WITH the word."
> Aquamarine is a procedural macro extension for rustdoc, that aims to improve the visual component of Rust documentation through use of the mermaid.js diagrams.
Quite neat. I’m unsure what are the benefits over providing an image (even vectorised, eg SVG), but it’s possible.
I've been tasked with single-sourcing some docs that we should've single-sourced from the start (which I suggested at the time). 3 doc sets, built from 3 different branches of the same GitHub repo. Comparing branches on GH shows 148 & 300 files different between main branch and the other 2. At least some of those files are the same in all 3 branches, so I don't trust that compare tool.
It's nice at least that more people agree with me now, I guess?
"Some explanations can, will, and should be written by code authors alone, or by those authors in partnership with LLMs. Others can, will, and should be conjured dynamically by code readers who ask LLMs for explanations on the fly."
Is there a way of getting Pandoc to detect a style or font in a DOCX file?
I'm specifically thinking of in-line preformatted text, so converting (say) a Source Code character style in Word to backticks for #Markdown or #AsciiDoc. Or a different paragraph style to a triple-backtick (or [source] for AsciiDoc) block.
Could this be scripted with Pandoc's Lua engine?
Or is there a better tool to do DOCX to AsciiDoc than pandoc?
Continued research on #OpenSource#documentation, and I've gotta say — as much as I like #markdown, it's really led us to a place where basically all docs everywhere look the same. Very little in terms of interactive docs or novel / inventive approaches to teaching. I mean, it's not a terrible place to be, just a bit... dull.
I'm going to be slightly contrarian and say that I like Discord. It's great to be able to get real-time help on a problem. And it is fun to see, again in real-time, what other people are working on and struggling with. In truth, Discord is no harder to sign up to than Slack, Matrix, […]
TIL that Go doesn't have bytes.Equal([]byte,string) or strings.Equal(string,[]byte) because as of 2019 the compiler is smart enough to make string([]byte) into a cast rather than a copy (possibly with allocation) when used in these types of comparisons.
I wish there was some central documentation of non-obvious "magical" optimizations like this.
bytes, internal/bytealg: simplify Equal The compiler has advanced enough that it is cheaper to convert to strings than to go through the assembly trampolines to call runtime.memequal. Simplify Equal accordingly, and cull dead code from bytealg. While we're here, simplify Equal's documentation. Fixes #31587
I got an #idea while I was half-dreaming this morning, what if #code#documentation had #advertisements in it? The more people use a #library, the more people read the documentation, and the more ad revenue you get. I’m still only half-awake and I haven’t seen this done before so there’s probably something very wrong with this idea I haven’t realized yet lol
If a function may return an error, it would be helpful if what errors might be returned are indicated somewhere (other than the bowels of the source code).
You can be the one to create the kbin page on wikipedia (en.wikipedia.org)
Secure a place in history. Create the source material for hundreds of journalists, bloggers and shitposters writing about the downfall of reddit and the rise of the threadiverse. (also missing!)...