Reorganize READMEs in the monorepo

[paulsmirnov]

We have two "main" README.md files in this monorepo, at the root and in the lib/ package. The app/ package doesn't have any. Both existing files have badges which is a bit misleading (but perhaps it is fine) --- and have led to fixing the badges twice, in #458 and #459.

It is normal to have many readmes in a repo, e.g. one root file and one per package (and even more). It should be clear from their content that there exists a hierarchy. We shouldn't repeat ourselves unless it is necessary.

Let's revisit this and decide on the number and the content of readmes.

[DmitryLukyanov]

From what I can say, they look good (I see only one line related to roolup for removing). The README on the main level says about Miew as about the tool (lib + app) where lib level considers Miew only as a library (only lib),

There are few notes:

1. Do we want to add this warning to the lib too:

⚠ It seems that experiments over recent years have led to application instability. We decided
to step back and proceed with architectural changes slowly. We apologize for any inconvenience
it may cause during the transition period. The old "master" branch is kept for your reference.
This is the new "main" branch for further development 🚀

2. I assume the below lib lines provide correct steps:

It integrates as a component into your web pages.

Installation and Usage

Miew library is available as an [NPM] package. Install it either with NPM:

npm install --save miew

or [Yarn]:

yarn add miew

Then use it in your [Webpack] / [Browserify] / [Rollup] setup, or just test it right in the Node
environment.

var Miew = require('miew');
console.log(Miew.VERSION);

You may also download the minified library and access it from the browser's
<SCRIPT> tag, or asynchronously include it via [Require.js]. Refer to the [tutorials],
[examples] and API docs for more details.

http://requirejs.org/
https://webpack.js.org/
http://browserify.org/
https://rollupjs.org/
https://nodejs.org/
https://www.npmjs.com/
https://yarnpkg.com/

I think in this list we have to remove only rollup?

[paulsmirnov]

@DmitryLukyanov

Re: banner. I think it is enough to have the only banner at the top of the repository.

Re: rollup. I don't even think we should remove rollup here. It is perfectly valid and is still used. The fact that we stopped using it for our builds doesn't mean that our users must do the same.

Re: scope. My primary concern was a surprise I got when I saw two readme's - I want to avoid such surprise for our users in the future. So, we must clearly separate the contents and hyperlink the files. We should also add a missing readme in the app package. The root readme must be an overview of the underlying packages. The confusion start from the first image in the root readme: it shows a demo application that is to be decommissioned soon 😁 Perhaps it's fine. However, we can try to reorganize the readmes.

[DmitryLukyanov]

3. Fun fact these fields are not even visible on the page:
   

The fact that we stopped using it for our builds doesn't mean that our users must do the same.

and in general, do we need to mention all tools users can use with the package? Is it not obvious? Just question, I don't really know such details.

The confusion start from the first image in the root readme: it shows a demo application that is to be decommissioned soon

so display mode and other configuration on the screenshot are only part of the demo app? I would say that the main part should also provide an "image" about how the library output looks/can look like to allow users see all information immediately when they enter to the main page. Does a note similar to: "Below you can find how the embedded miew can look like. Please see %a link on app% for details"?

[paulsmirnov]

Here is the plan as a result of the discussion:

• add a readme to the app/ package,
• improve the readme in the lib/ package (more structured way to present links to docs and examples),
• improve the readme in the root (more structured way to present all packages).