Documentation (for mere mortals)

Ask for new features here.

Moderator: Pablo

Post Reply
yalu
New Member
Posts: 4
Joined: Mon Dec 21, 2009 8:50 pm

Documentation (for mere mortals)

Post by yalu » Fri Jan 01, 2010 10:55 pm

I definitely like the idea of a remote-bootable mythtv frontend but I think the documentation could do with some improvements. They read a bit like the on line equivalent of a man page. They document how Minimyth *works* (which works well for the booting setup). If you read them from a perspective of a user trying to get it up and running, things are sometimes less obvious.

I'll be constructive.

The first question that rose with me was "There's read-only and read-write configuration; which do I create/modify?" (it's probably the read-only file).

Under the title "Configuration obtained from the MiniMyth configuration file" it says "The MiniMyth configuration file is called 'minimyth.conf'." Maybe it's better to say "the read-only configuration file blabla etc", to avoid confusion.

In the next paragraph, you say "The MiniMyth configuration package is called 'minimyth.pm'.". Now it becomes clear after a while that this means a Perl package etcetera, but I think it's best to clearly state from the start of the paragraph "by 'package' we mean a programmers concept in the Perl language; so this configuration option is here for people with programming experience who need more control and want to customize the way Minimyth is configured". I would also try to avoid reverse chronological descriptions like "At startup, MiniMyth executes the package's 'start' method after retrieving and importing (but not processing) the MiniMyth configuration file and after updating DHCP configuration.".

At last, the documentation sums up all configuration methods and all options you can use in each method, (=typical "man page" approach"), but the most useful thing to add is, I think, a short intro about what CAN be changed and what absolutely NEEDS to be changed. It would also be useful to state here what you can expect from a bootable Minimyth in its default configuration. I, for example, do not know if a prompt saying

Code: Select all

login:
is really the thing I'm supposed to be looking at with a non-configured Minimyth. What's the minimum configuration to get things running? Do you have to configure X, or only (eg) if you need proprietary drivers?

I'd happily write this up, if I knew how to actually get Minimyth working :-)

Post Reply