Include development info in README?

Question

Include development info in README?

sivaraam opened this issue 2 years ago · comments

Previously the repo's README used to be a link to _includes/README.md. It's now a normal file with some information about the site. It is nice for the landing page.

Though, now it lacks basic instructions that would help someone to know how to spin up the site for development locally. Would it be helpful if we include it in the repo's README in some way?

Christian Couder · Answer 1 · Wed Oct 26 2022 16:41:38 GMT+0800 (China Standard Time)

Thanks @sivaraam for noticing this and opening this issue!

I agree it would be helpful to include the basic instructions that would help someone to know how to spin up the site for development locally!

Christian Couder · Answer 2 · Wed Oct 26 2022 16:44:14 GMT+0800 (China Standard Time)

@utkarsh006 I think we should have been a bit more careful with #606

Kaartic Sivaraam · Answer 3 · Mon Oct 31 2022 01:48:03 GMT+0800 (China Standard Time)

I just realized the landing page of git.github.io is actually present in index.md in the root of the repo. The new README in the root of the repo also seems to be based on it.

I'm wondering if we should just make the README to point to _includes/README like it used to given that it served us well all this while. If we feel anything from the new README worth keeping (the contributor list?), we could think of moving it over to _includes/README.

Let me know your thoughts.

Christian Couder · Answer 4 · Wed Nov 30 2022 04:02:36 GMT+0800 (China Standard Time)

@sivaraam sorry for not replying earlier.

I agree that it would be nice to have basic instructions to know how to spin up the site for development locally. Could we put them in the README.md?

Would it work to then remove both _includes/README.md and index.md altogether and keep only README.md? Which pages were including or linking to _includes/README.md, and what kind of link it was? A symbolic link?

It looks to me like only the "about" page is currently including README.md. Also I think symbolic links are not very friendly for Windows users, so it would be nice if we wouldn't use one.

So another possibility might be to have both README.md and about.md include _includes/README.md with the latter having the same content as the current README.md and the basic instructions to spin up the site.

What do you think?

Kaartic Sivaraam · Answer 5 · Mon Apr 17 2023 03:14:31 GMT+0800 (China Standard Time)

So another possibility might be to have both README.md and about.md include _includes/README.md with the latter having the same content as the current README.md and the basic instructions to spin up the site.

I tried to do this, Christian. It seems we can't have a single README which unifies the content for root and the index page of the site. The badge at the end and the contributor list don't seem to render well via Jekyll. So, I've tried to keep them separate (cloning common portions). Let me know if that's fine.