Re: [Mingw-cross-env-list] Do we still need a plain text README?

[Tony Theodore]

On 8 February 2010 10:54, Volker Grabsch <address@hidden> wrote:
> Tony Theodore <address@hidden> schrieb:
>> >
>> > On the other hand, every plain text fan can browse the
>> > doc/index.html with the favourite text browser, [...]
>>
>> Trying to read html in a text editor is painful,
>
> JFTR: I was talking about text browsers, not text editors.
>
> To put it another way: "less" and "lynx" are just different
> viewers. Is it really a big difference to type
>
>    lynx index.html
>
> instead of
>
>    less README
>
> ?

Not a big difference in typing, but lynx would be preferable if it's
available. I was thinking of

    less index.html

and that isn't friendly for anyone looking for help. I think of lynx
as a web browser, and it's probably safe to assume that everyone has a
web browser for their environment (text/gui/reader...).

>> however, if people
>> run into problems, they will most likely need a web browser of some
>> sort anyway, so not generating a plain text copy of index.html won't
>> really affect them.
>
> That's another issue. However, I hope the included documentation
> is helpful enough to make surfing in the web unnecessary.
>
>> Thinking about a first time user though, the least surprising thing
>> would be to have a plain text README in / rather than /doc.
>
> Well, initially I really wanted to put README and ChangeLog into /,
> but I feared that might clutter it. When you unpack the current
> release, you'll find exactly three items:
>
>    doc/
>    src/
>    Makefile
>
> I think this is pretty self-explainatory even to novices. It is
> clear that help is to be expected in the doc/ subdirectory, and
> that running "make" might be a good idea.
>
> However, entering doc/ things are no longer that clear:
>
>    ChangeLog
>    index.html
>    README
>    screenshot-4th-compile.png
>    screenshot-4th-compile-small.png
>    screenshot-4th-run.png
>    screenshot-4th-run-small.png

I'd put the images in an images directory.

> It is not obvious where to start. Which is the "right"
> documentation? README or index.html?

Yes, this could be confusing and frustrating, people may read both
thinking one might be slightly different than the other.

> On the other hand, moving README (and ChangeLog) to /
> might unclutter that subdirectory. Also, the README might
> contain a pointer to doc/index.html instead of the text
> browser dump.
>
> So all in all, I see the following possibilities:
>
>    A)  leave everything as it is
>
>    B)  move README and ChangeLog from doc/ to /
>
>    C)  same as B), but README contains only a pointer
>        such as "see doc/index.html"
>
>    D)  remove README, keep ChangeLog in doc/
>
>    E)  remove README, move ChangeLog from doc/ to /
>
> Any opinions on that? What do you think?

I was thinking the ideal README would be a quick start that explained:

make
make gcc
make list of relevant packages
setting environment variables
pointer to doc/index.htlml

However, there is no real quick start. The bare minimum is gcc and
people will have ample time to read the docs while they wait (though
they will be waiting much longer if they don't read the docs first).

A placeholder (with just a pointer) would be distracting, people would
find doc/index.html more quickly without it.

That leaves me with D or E, and I'm ambivalent about ChangeLog. It's
not confusing in either directory, particularly since it doesn't
contain instructions on upgrading (as some do). I'd lean toward
putting it in / , but having Makefile on it's own will probably get
the target audience started sooner.

Regards,

Tony