I consider this issue as 'Critical' because readme is widely adopted to contain general information. Despite this, many projects make readme become too verbose or even too brief.

This is part of issue #129 that aims to clarify the purpose of readme and to ensure this file is not dumped with much information that most people don't read.

The verbosity

While randomly browsing the history for readme, I didn't find any commit (including mine) that actually helped to reduce the amount of text being included. All commits seem to contribute the document to become 'comprehensive' and more 'technical' that most people will not want to read (including myself).

Unfortunately, there is no particular readme style that is widely known as "good" standard. Many projects make the readme file too verbose or decide their own standard. As for this project, the existing readme contains multiple SECTION that resembles GNU man pages or GNU Coding Standards in general.

We shall understand that complying to an established standard is to follow a recommendation, but not a compulsion. There is no reason to strictly follow a particular standard, especially if that cause readme to be less likely to be read by most people.

The misleading "good readme"

Quick googling using "good readme" keywords might lead to this post on StackOverflow that had asked on "How to write a good README" in 2010. Just because the link is found within top 3 results, that doesn't mean we have found the answer. In fact, the question might be perceived as "opinion-based" thus, the accumulated answers are also seem to be the same. Again, no widely known "good" standard.

Proposed changes

The better answer was actually found in this post on Programmers Stack Exchange that had asked on "What information should be in the github README.md?" in 2013. This was found in the second page of result, within top 20, using the same keywords mentioned earlier.

In that post, the only given answer by Bryan Oakley is quoted below:

I expect to see an introduction and brief overview. There should be something there to convince me that the project solves a particular problem. After reading the README, I should know enough information to know what the project does, what it requires, how to build it, and how to use it. That information doesn't all need to be in the README, but links to that information should be.

Splendid! This answer mentions all important points within a paragraph of four lines. Following this, I have no other words to explain anymore.

Markdown syntax

Following the simplification for the change log, in addition to -------------- for H2 level formatting, this ========== for H1 level formatting also will be used (may be used for top title only). There are just two levels of heading when using underline-ish syntax, which is sufficient for readme.

I have only seen handsful of projects that adopt underline-ish syntax and keeping it tidy for the readme E.g. Debian/README.Debian and its raw text. Another example that is found outside GitHub, however more text but still tidy, is this plain text readme from Tiny Core Linux project.

For including links, I would suggest referenced links will do better job than inline links, for keeping the text tidy and readable. Therefore, when viewing as raw text, all links will be listed at bottom of page instead of cluttering text within the paragraphs. This makes the raw text remain readable.

Raw text:

[inline link](https://github.com/clearkimura/Customizer/issues/134#)
[inline link, relative](#)
[referenced link][1]
[referenced link, relative][2]

[1]: https://github.com/clearkimura/Customizer/issues/134#
[2]: #

Markdown:

inline link
inline link, relative
referenced link
referenced link, relative

Expected appearance of README.md

When viewing as raw text:

Customizer
==========

Customizer, formerly known as U-Customizer, is an advanced Live CD customization
and remastering tool. Use any supported Ubuntu-based ISO image, such as Ubuntu
Mini Remix, Ubuntu or its derivatives ISO image to build your own remix or custom
ISO image with a few mouse clicks.

For quick reference, refer to [manual]. More information in [wiki].

Acknowledgements
----------------

Customizer was founded and developed by Ivailo Monev 'fluxer' and has been
improved by many [contributors].

Distributed under GPL-2.0 [license].

Development
-----------

Customizer is stable and not under active development.

The original repository is kept as "old stable", which is subject to tentative
updates of bug fixes and clean up. This supports up to Ubuntu 14.04.

Future development has moved to the fork, which aims to migrate the code
to Python 3 and Qt 5. The fork will support newer releases of Ubuntu.

This repository
---------------

You are viewing the original repository of Customizer.

The repo was previously maintained by Ivailo Monev 'fluxer'.
This is currently maintained by Mubiin Kimura 'clearkimura'.

The official fork is available at [kamilion/customizer].
The fork is maintained by Graham Cantin 'Kamilion'.


[manual]: ./../blob/pre413/docs/manual.md
[wiki]: ./../wiki
[Contributors]: ./../blob/pre413/Contributors
[license]: ./../blob/pre413/COPYING
[kamilion/customizer]: https://github.com/kamilion/customizer

When viewing as Markdown:

Customizer

Customizer, formerly known as U-Customizer, is an advanced Live CD customization
and remastering tool. Use any supported Ubuntu-based ISO image, such as Ubuntu
Mini Remix, Ubuntu or its derivatives ISO image to build your own remix or custom
ISO image with a few mouse clicks.

For quick reference, refer to manual. More information in wiki.

Acknowledgements

Customizer was founded and developed by Ivailo Monev 'fluxer' and has been
improved by many contributors.

Distributed under GPL-2.0 license.

Development

Customizer is stable and not under active development.

The original repository is kept as "old stable", which is subject to tentative
updates of bug fixes and clean up. This supports up to Ubuntu 14.04.

Future development has moved to the fork, which aims to migrate the code
to Python 3 and Qt 5. The fork will support newer releases of Ubuntu.

This repository

You are viewing the original repository of Customizer.

The repo was previously maintained by Ivailo Monev 'fluxer'.
This is currently maintained by Mubiin Kimura 'clearkimura'.

The official fork is available at kamilion/customizer.
The fork is maintained by Graham Cantin 'Kamilion'.

Markdown discrepancy

In above, raw text contains manual newlines to develop into static paragraphs.

• When viewing as Markdown within GitHub issues, text will be not be wrapped;
• In contrast, when viewing as Markdown in code repository page, the same text blocks will be automatically wrapped to fill the page

When using relative link in README.md, actual link would just be:

• i.e docs/manual.md instead of ./../blob/pre413/docs/manual.md;
• i.e. COPYING instead of ./../blob/pre413/COPYING
• Links are subject to changes, when clean up may take place in next milestones

Leftover text

The existing readme contents are still valuable and may be useful to implement manpage by future contributors. While most of existing contents will be removed from readme, I intend to keep those in a new separate file at docs/manual.md. Technical information may be updated there, so that there won't be any duplicate efforts later, when the readme has been simplified.

I hope to implement this changes soon or latest by future release 4.2.0