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

[Volker Grabsch]

Tony Theodore <address@hidden> schrieb:
> On 8 February 2010 10:54, Volker Grabsch <address@hidden> wrote:
> > 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.

That's true, but IMHO viewing an HTML with a text viewer is
as absurd as viewing a text file with a hex viewer.

> >    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.

I thought about that at the very beginning, but I thought
that a single index.html along with some images would be
more than clear enough. I.e., if you look into the doc/
directory and see

    index.html
    screenshot-4th-compile.png
    screenshot-4th-compile-small.png
    screenshot-4th-run.png
    screenshot-4th-run-small.png

then everything is clear, isn't it? Note that this works
especially well because "s" comes after "i" in the alphabet.

> > 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.
[...]
> A placeholder (with just a pointer) would be distracting, people would
> find doc/index.html more quickly without it.

These arguments in combination show an important point against
having a README, I think.

> > So all in all, I see the following possibilities:
[...]
> >    D)  remove README, keep ChangeLog in doc/
> >
> >    E)  remove README, move ChangeLog from doc/ to /
[...]
> 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 /

Me too, because of the argument above: An uncluttered doc/
directory won't need any subdirectories for images, etc.

> but having Makefile on it's own will probably get
> the target audience started sooner.

Well, let's take a look at the new / directory:

    doc/
    src/
    ChangeLog
    Makefile

I don't think the ChangeLog is very distracting here.

However, we might think about leaving ChangeLog out.
Does anyone seriously look at the ChangeLog? If one is
interested in the development, one usually pulls the
development version, and there an "hg log" will be of
more value than a ChangeLog.

One could also think about integrating the ChangeLog
into doc/index.html. But that would be very counter-
intuitive and would make the ChangeLog even less useful
than it already is.

So what do you think? Should we keep the ChangeLog or
sould we also remove it?


Greets,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR