linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] README: Find more sane first words we have to say about Linux
@ 2017-04-30 20:11 Martin Kepplinger
  2017-05-01 15:24 ` Jonathan Corbet
  0 siblings, 1 reply; 3+ messages in thread
From: Martin Kepplinger @ 2017-04-30 20:11 UTC (permalink / raw)
  To: mchehab, akpm, corbet, torvalds; +Cc: linux-kernel, Martin Kepplinger

Imagine you're completely new to Linux, just real quick, ok? What do you do?
Wouldn't having a look at README be under first if no *the* first thing?
Ah there it is: README. "Linux kernel". nice! So what's that?
"This file was moved to ...... Please notice that there are several....".
Wtf!? Why? Can't they just tell me what's going on like a normal person?

I'm sorry for the exaggeration, but really honestly I think we could do better.
I'm all for not really having content in README, but come on :)

I only try to avoid the biggest damage here and find some nice first words
at least.

Signed-off-by: Martin Kepplinger <martink@posteo.de>
---

please ignore if too irrelevant, but I personally would put this in 4.11,
if still possible, and rewrite the REAME for 4.12 to be even more friendly.

thanks
                         martin



 README | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README b/README
index b2ba4aaa3a71..876a98a5d472 100644
--- a/README
+++ b/README
@@ -1,10 +1,11 @@
 Linux kernel
 ============
 
-This file was moved to Documentation/admin-guide/README.rst
+Linux is a Unix-like operating system, originally written by Linus Torvalds.
+Please read Documentation/admin-guide/README.rst for an introduction.
 
-Please notice that there are several guides for kernel developers and users.
-These guides can be rendered in a number of formats, like HTML and PDF.
+There are several guides for kernel developers and users. These guides can be
+rendered in a number of formats, like HTML and PDF.
 
 In order to build the documentation, use ``make htmldocs`` or
 ``make pdfdocs``.
-- 
2.11.0

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] README: Find more sane first words we have to say about Linux
  2017-04-30 20:11 [PATCH] README: Find more sane first words we have to say about Linux Martin Kepplinger
@ 2017-05-01 15:24 ` Jonathan Corbet
  2017-05-01 16:01   ` Martin Kepplinger
  0 siblings, 1 reply; 3+ messages in thread
From: Jonathan Corbet @ 2017-05-01 15:24 UTC (permalink / raw)
  To: Martin Kepplinger; +Cc: mchehab, akpm, torvalds, linux-kernel

On Sun, 30 Apr 2017 22:11:35 +0200
Martin Kepplinger <martink@posteo.de> wrote:

> Imagine you're completely new to Linux, just real quick, ok? What do you do?
> Wouldn't having a look at README be under first if no *the* first thing?
> Ah there it is: README. "Linux kernel". nice! So what's that?
> "This file was moved to ...... Please notice that there are several....".
> Wtf!? Why? Can't they just tell me what's going on like a normal person?

So I don't doubt we could put something better there, but can we think for
a moment about who the audience is here?  If you're "completely new to
Linux", will you really start by jumping into the kernel source tree?
Somehow I'm not quite convinced...  It seems to me that the README file
should be aimed at developers who know what the kernel is but are not yet
familiar with the process of configuring and building it.

Thanks,

jon

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] README: Find more sane first words we have to say about Linux
  2017-05-01 15:24 ` Jonathan Corbet
@ 2017-05-01 16:01   ` Martin Kepplinger
  0 siblings, 0 replies; 3+ messages in thread
From: Martin Kepplinger @ 2017-05-01 16:01 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: mchehab, akpm, torvalds, linux-kernel

Am 2017-05-01 um 17:24 schrieb Jonathan Corbet:
> On Sun, 30 Apr 2017 22:11:35 +0200
> Martin Kepplinger <martink@posteo.de> wrote:
> 
>> Imagine you're completely new to Linux, just real quick, ok? What do you do?
>> Wouldn't having a look at README be under first if no *the* first thing?
>> Ah there it is: README. "Linux kernel". nice! So what's that?
>> "This file was moved to ...... Please notice that there are several....".
>> Wtf!? Why? Can't they just tell me what's going on like a normal person?
> 
> So I don't doubt we could put something better there, but can we think for
> a moment about who the audience is here?  If you're "completely new to
> Linux", will you really start by jumping into the kernel source tree?
> Somehow I'm not quite convinced...  It seems to me that the README file
> should be aimed at developers who know what the kernel is but are not yet
> familiar with the process of configuring and building it.
> 

It should definitely be aimed at developers. But even as a developer who
is completely new to kernel development, it's nice to have some broad
context in 2 or 3 lines first.

(again, I'm a little exaggerating and) trying to see from an outside
point of view:
What other "official brief definition" of what Linux is could there be?
Right now one has the impression that the Linux Foundation has
"official" information, but that's (very strictly speaking) pretty
random right? Besides developers, I can imagine technical literature to
have a look at projects' README files for that.

I mean there *is* the new README.rst which is awesome. But it wouldn't
hurt to summarize the first few things in the README and then refer to
the doc. It should be something for people who

* already checked out the source obviously (developers, but or technical
authors, or any interested engineer), and

* who would *maybe* say, "what? nothing in the README? ok. I'll take
some definition I found online then" and not bother reading the
Documentation directory just yet.

                      martin

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2017-05-01 16:01 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-04-30 20:11 [PATCH] README: Find more sane first words we have to say about Linux Martin Kepplinger
2017-05-01 15:24 ` Jonathan Corbet
2017-05-01 16:01   ` Martin Kepplinger

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).