Hacker News Reader

Comment by random_cynic | Hacker News Reader

> https://mpv.io/manual/ Linked from straight from the mpv homepage

That's just the manpage in html format, are you kidding? We're not in the era of text terminals, there are so many tools for writing good documentation that this is just inexcusable. Take a look at VLC documentation (https://wiki.videolan.org/Documentation:User_Guide/), that's a proper documentation with screenshots that looks like someone actually put some effort into writing that so that it is understandable to new users instead of plugging words into a troff file.

Except for the edge case of controlling a media player from another application you've put no convincing use case for using mpv over vlc. So it's a personal preference not that mpv is superior to vlc in anyway (actually far inferior for most use cases).

View on HN

> Take a look at VLC documentation (https://wiki.videolan.org/Documentation:User_Guide/)

Trust me, I have. Extensively. The mpv manpage (which is actually written in the reStructuredText markup lanugage) is comprehensive and easy to read. Era of text terminals? Give me a break, I just gave you a link for reading it in your browser, just like the VLC wiki, except the mpv manual is very comprehensive and up to date, while the VLC manual is scattered, sparse, and frequently out of date. I practice terminal emulator avoidance; I don't edit text in a terminal emulator, I don't read manpages in a terminal emulator, and I almost never start mpv from a terminal emulator either.

> So it's a personal preference not that mpv is superior to vlc [...] most use cases [...]

I have been upfront about that. I recommend VLC to the vast majority of users, including all of my family and most of my friends.

You completely missed the point about man pages. It doesn't matter what the man page was written in, it's still a man page, optimized for viewing in text terminal. It makes no sense to use this format for web browser. Vlc also had a man page, but the developers know the difference between a man page and proper documentation. It's completely unsuitable for new users using any sufficiently complex application like a video player.

What it was "optimized for" is irrelevant if it's legible and has good information. The mpv manual read in a web browser is both of those. The VLC manual is a mediawiki (if we're talking about subjective appearances, mediawiki has always been fugly) that's both sparse and out of date. Changes to mpv make it into the manual because they're both in the same repo and people making changes to the code are expected by community convention to have the corresponding updates to the manual in their pull request. This doesn't happen with VLC.

The only upside of the VLC manual is that only one in a thousand VLC users will ever need to look at it in the first place. mpv's manual is necessary but high quality, while VLC's manual is low quality but extraneous.

> What it was "optimized for" is irrelevant if it's legible and has good information.

It's not having good information that is important, what's critical is finding relevant information quickly, tagging and linking it to other parts of the document and external sources. Also information does not have to be limited to text format, especially for manuals a graphic or a small video can be worth more than thousand written words. Welcome to 21st century. All information you'll ever need is present in the source code, then why even bother creating a documentation? Manpage is limited for even text terminals, texinfo is so much better.

I agree regarding the need to keep the documentation updated. However, it's quite easy to get support from the community and putting a request to update an outdated article or section.

Reply on news.ycombinator.com