|
|
|
|
|
|
by kaba0
1084 days ago
|
|
|
Thank you for this discussion and article, both were an interesting read! One tiny criticism regarding the article: I was hoping you would actually color code the HTML code samples visually, I believe it would have aided understanding better. You could have even used a more realistic/concrete sample as well. |
|
|
In 2021 I prototyped some documentation single-sourcing tools. I made leaps fueled by intuition and years of frustration, so I found it hard to explain to others what I did and why.
In early 2022 I started sketching this post as ~intellectual-groundwork on the ~motivating problems I saw in existing markup languages. What I hoped would be a few weeks stretched into several months of drafts I wasn't happy with.
Trying to write one _coherent_ motivating post made it clear just how many iterative intuitive leaps I'd made along the way, so I started splitting out asides/sections into posts to make incremental progress and show my math. (The linked post is currently the most-recent of 6 on documentation at https://t-ravis.com/room/doc/; the other 5 have seeds in it.)
Color-coding the examples was indeed on the to-do list from early on, but after starting over a few times and still feeling unsure it would communicate, I got frustrated enough (exacerbated by unrelated ~burnout) to just shove it out the door and turn to other fires for a while. (Part of why I haven't made a follow-up post, even though I intend to.) It's been better received than I feared, so it probably makes sense to go back and improve those when I start the next post in the series.
(You can see where it falls in the rough outline of the broader intellectual project at https://t-ravis.com/post/doc/the_trouble_with_anonymous_gizm...)