Posted on 2024-07-19

Documentation

ghorwood wrote:

how did “documentation” become six youtube videos of conference talks and a discord channel? was there something wrong with opening a text editor and just typing out how your project works? did people at some point say “i hate scannable, searchable references”? was there a study that showed copy-pastable examples cause cancer?

it’s 2035 and your api reference is now six emojis, a folk song, a short series of improv scripts and the zapruder film with subtitles. if you have any questions, contact us on nextdoor or call this 1-900 number.

technicat responded:
@ghorwood I expect text scores higher on accessibility than video of a laptop screen. Where's the alt text police when you need them?

hairylarry responded:
@ghorwood 

I have always been a proponent of text documentation for every stage of the project. Back in the day I wrote "The Document Is The Program" for Freshmeat (now defunct).

Now a good specifications document. With code walkthroughs? (code free code walkthroughs) Now that will save you some time. It's a lot less work to write the document than it is to code to an ambiguous spec.

Look I know it's going to change. But you still have to know where to start.

---

Here's the link:
https://gamerplus.org/deck/@ghorwood@mastodon.social/112813345157926621

If you're not on Mastodon or some other federated server already you are welcome to try 

https://gamerplus.org

Believe me, the conversations are better.