one large `README` instead of a multi-page documentation site

[yegor256]

I believe, it would be more convenient for users, if you generate the entire documentation as a single long Markdown document and then inject it into the README.md on every push, making a pull request with the changes. Then, you will merge the pull request and the project face will be updated. We do this, for example, in this repo: https://github.com/yegor256/micromap/blob/master/.github/workflows/benchmark.yml

Motivation:

• The navigation will be easier
• Formatting will be GitHub native (no need to get used to your own style)

[deemp]

I assume your comment is about our site (link).

I believe, it would be more convenient for users, if you generate the entire documentation as a single long Markdown document

GH Markdown makes section names at certain level so small that they're almost indistinguishable from bold text. The site does have pages with nested sections. Hence, the text structure in a single Markdown file may be non-obvious. Example:

Section name

Section body

Additionally, the site contains sections that are of no interest for a user, e.g., Contributing. I don't think users would like to scroll through them in the README.

We do this, for example, in this repo: https://github.com/yegor256/micromap/blob/master/.github/workflows/benchmark.yml

Do you suggest that we make pipeline results more prominent?

We currently have a link to the report (link) in the Introduction section on our site (link).

I can agree that this link is not very discoverable. To fix this, I can additionally put it into the README.

However, I can't agree that we should include the whole report into the README.

1. The report is large. It's not convenient to scroll through it in the README.
2. It's impossible to make the report interactive and well-formatted in the README due to GH limitations for JS and CSS.
3. I believe the full report in the README is of no interest for a user. So, I prefer to have a dedicated page that
   1. Explains (almost) everything about the results
   2. Provides the summary of results
   3. Provides the results

[deemp]

I believe, it would be more convenient for users

Why do you believe so?

The navigation will be easier

What is not easy about the current navigation?

[yegor256]

@deemp I can't prove it: https://stackoverflow.com/questions/78519596/what-is-better-a-single-long-readme-file-or-a-set-of-smaller-cross-linked-pages but it seems that one long README is a good practice now

[deemp]

We do have TOC.

[yegor256]

@maxonfjvipon @volodya-lombrozo what do you think?

[maxonfjvipon]

@yegor256 @deemp If it's possible to have both - long readme and website - let's have both. If there's only one option - I vote for a readme because project is not that big and there are not so many sections and subsections.

[deemp]

@yegor256, @maxonfjvipon here's some evidence that a README shouldn't contain the whole documentation. So, I vote for a short README with the most important links.

link

link

[yegor256]

@deemp currently, there is nothing in README. If you move "the information necessary for developer to get started and contributing" -- 50% of your documentation site will end up being in the README. Then, the question is: why not 100%? Where is the line?

I believe that the links above are mostly about Javadoc (or similar) documentation generators, which indeed are very verbose and should not be placed in README. If this project is planning to have such an API doc -- definitely let's keep it in a separate site. However, currently, your documentation site contains what usually people keep in the README.

[deemp]

@yegor256

the information necessary for developer to get started and contributing

I assume something like this. Any downsides?

https://github.com/haskell/haskell-language-server

[yegor256]

@deemp yes, this is what looks wrong, if you ask me. And the authors of the links you quoted above would agree with you :)

[deemp]

However, currently, your documentation site contains what usually people keep in the README.

@yegor256, I'm not convinced. I think I can agree or accept your suggestion in two cases.

1. You show me:
   • The data on the number of repos with:
     • docs sites only
     • README only
     • both
   • That repos with a README only prevail
2. You set a clear policy for the objectionary organization what should go into a README
   • The policy should explain what to do about:
     • interactive elements
     • custom styling
     • math notation
     • lots of data like our report or normalizer Haddocks
     • acceptable section nesting level
     • etc.

[yegor256]

@deemp how about we just stick to the formula suggested above by yourself: "README should be a short overview and quick start" (it seems that most people agree, in the poll). Once it's done, you will see how much is left for the auto-generated static site.

[deemp]

@yegor256, I don't mind to try, so I created https://github.com/objectionary/normalizer/issues/368.