Re: instructions for new users... no readable README?

On Sun, 31 Jan 2021 15:59:11 -0600, Robert Eden wrote:

> Now that we have a working xmltv.exe,  Today I looked at the "gmake 
> windows_dist" script that used to build the windows distribution.
> Previously, a separate README.Win32 existed, which was converted to a 
> README.TXT in the zip file.   I figured it would be easier to have the 
> Windows README simply reference the main readme and quickstart to make 
> it easier.
> 
> Well, there isn't a "readable"  README file in the source distribution 
> any more!!!  There is the README.md, but that's not a very human 
> readable.  Should it be converted to README.html or README.txt??  I 
> assume there are tools to do that.   I'm not sure it's a good idea to 
> assume people read the README on github.
> 
> What sort of "flow" do we expect new users to follow to learn about how 
> to use the project?
> 
> Robert

I think we have to assume the workflow for Windows exe users will be very different to that for people using the perl code direct (e.g. Linux, cygwin, Strawberry).

The readme.md markdown on github is heavily focused on the technicalities of installing the perl source, which won't be of interest to .exe users.

And from the questions which get asked it seems .exe users have a need for more info on exactly how to run the grabber of interest. This is lacking in the current docs, since we assume people will look at the man pages to find out how to run things. Not so with .exe build users I suggest.

The doc/QuickStart page has useful info but, I think, launches too quickly into filtering the output into lots of different outputs (most of which will be of no interest to .exe users).

I think .exe users are more interested in the basics: what does the xmltv package do? how do I find a grabber for my tv? what channels does it contain? how do I run it? how do I get my listings into MythTV/TVHeadend/XBian/whatever. This last one is a potential can-of-worms but a one-liner 'typical' usage would help a lot of people.

Geoff