Hacker News new | past | comments | ask | show | jobs | submit login

In my opinion, "creating a coding tutorial" and "creating/updating documentation" are two things that seem conflated here when they're very different workflows.

I wouldn't ever prefer to create a video tutorial rather than just write out documentation. It's just too far from my workflow (maybe that's just me).

I can, however, see how something like this would be extremely valuable to people who are instructing others on how to write code (DevX, bootcamp instructors, people who do video coding tutorials). I think that "Document your code just by hitting 'record'" is overselling that value though.




TL;DR The Grand Unified Theory of Documentation: https://documentation.divio.com/

There's a lot that is mistakenly conflated as "documentation".

Sometimes I would know enough about a topic except for one little thing and would look to the documentation. I only needed information on that one little thing to be productive, but I'd get stuck reading someone's entire backstory, trying to skim and find the one useful line in a random example to help me.

Other times, I would find documentation and struggle to follow it in practice until I came to the conclusion that I would need to read the whole thing in its entirety to become productive. I would either have to block out some time to learn it all or go with a completely different solution.

I used to think projects that claimed to be documented either fit into two groups:

1. Good documentation: I can find what I'm looking for

2. Bad documentation: I can't find what I'm looking for

My eyes were opened when I read something that I have since committed to memory: https://documentation.divio.com

There isn't just good documentation and bad documentation, there are 4 different kinds of documentation for distinct types of information delivery: Tutorials, How-To Guides, Explanations, and finally Reference.

Now I consider documentation good or bad based on if it contains all 4 kinds of documentation.


Wish this were higher up; lots of discussion here assumes this is for reference documentation when it's only relevant for usage docs.


They're definitely two different workflows and for every day work, creating a video tutorial or a "codelab" is a lot more work than just writing some Markdown text in a README.

Creating incentives within a work environment to write better documentation is easier than trying to record video tutorials.

I agree it looks like a good tool for producing instructional videos.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: