Poll: What Type of Documentation do You Like Better? | Hacker News Reader

Poll: What Type of Documentation do You Like Better?

3 points_gd3l9 comments

Hey all, I'm launching a new app soon, and I'm curious about what types of documentation for websites/apps/learning things you like better: written (i.e. pdf eBooks of documentation) or video (i.e. screencasts).

View on HN

As has been said: Good written documentation is essential. If only for ease of looking at an index to jump straight to a specific section instead of having to 'guess' what part of a video I need to skip through to watch a specific bit...

...that said, screencasts and the like can be invaluable for actually demonstrating things like using convoluted software or coding for example!

Ideal world: Thorough, clear and well organised written documents are a must, use videos to 'highlight' things that don't come across well in the documentation or demo things!

Very well said, thanks man. I agree and think relying solely on videos is a mistake. I'll still use it for my new project because for noobs I think a video is good.

A few videos are useful and great to have, but they are not replacements for good written documentation. Often, I don't want to or cant watch a video but can read written documentation (or I can watch videos, but without sound..). For programming related documentation, I usually just close the browser tab if the documentation I find is only in video format - I often won't even bother trying. For programs, I don't do it as often, but I've done it enough times that it matters. Often I'd rather google for five minutes than watch a five minute documentation video. Other times, the video is too slow or too fast for my taste and I end up skipping most of it anyway.

Also, I can easily perform text search for something in written docs, but not in videos.

Bottom line: written documentation is a must have, video documentation is very nice to have, but IMHO should never be a replacement, but rather an added bonus.

Great feedback, I appreciate the input. My app is going to target noobs, so I think the video component will be super helpful. But for experienced people, yeah I know what you mean. It can be a roadbump at best sometimes.

If you're targeting beginners, then I would put more emphasis on videos than I did in my comment above, but I would still not completely replace the written docs with them. Also, the written docs should probably contain step-by-step instructions for common tasks, with screenshots (basically like the video version would be but not a video).

Of course, you may not have the time/resources to do all that so you will have to decide whats most valuable for your customers. Ideally, I'd say written docs hopefully with screenshots and at least one video, if you can.

Thanks man, that's sort of my plan right now anyway. Iwas going to rely more on video but after the surprising (to me) response to this poll I'm definitely going to lean more heavily on text with the videos and screenshots sprinkled throughout.

Unless you are a very poor reader, written documentation is simply faster to absorb than videos. Videos are a huge time-suck in comparison, for the same amount of info.

Full Examples + Demos. I hate when a video tutorial or written documentation talks about something and shows a few lines of sample code but doesn't actually let you download the full working code.

Being able to download code is huge, and I think that should be a standard for code-related tutorials.

However, what about tutorials for setting an app? Wouldn't you rather watch a setup video than read through a pdf?

Reply on news.ycombinator.com