Stream: ibm
Topic: Project documentation
Lee Surprenant (Nov 08 2019 at 19:41):
Paul did a really nice job standing up a project site in time for our announcment
Lee Surprenant (Nov 08 2019 at 19:41):
However, one thing I'm still not totally comfortable with is the blurry line between our documentation on github and what we put up on the site
Lee Surprenant (Nov 08 2019 at 19:42):
for example, i just noticed that we now have 2 different CONTRIBUTING files...one at the project root and one under docs
Lee Surprenant (Nov 08 2019 at 19:43):
in my opinion, that content should live at the root of the project on github
Lee Surprenant (Nov 08 2019 at 19:44):
if we want, we could copy it into the site, but i'm not sure how much value that has
Lee Surprenant (Nov 08 2019 at 19:44):
I captured some of this in https://github.com/IBM/FHIR/issues/390
Lee Surprenant (Nov 08 2019 at 19:46):
things that live today in github are:
- README.md (content mostly duplicated into docs/src/pages/index.md)
- CONTRIBUTING.md (content mostly duplicated into docs/src/pages/CONTRIBUTING.md)
- MAINTAINERS.md
- LICENSE
- select module-level READMEs like https://github.com/IBM/FHIR/tree/master/fhir-persistence-schema
Lee Surprenant (Nov 08 2019 at 19:47):
I'm thinking to fix #390 by dropping CONTRIBUTING from the site
Lee Surprenant (Nov 08 2019 at 19:47):
but unfortunately our landing page has a link to that. and this comes from our README
Lee Surprenant (Nov 08 2019 at 19:49):
I'm wondering if we should just go for a clean split. project docs like READMEs and CONTRIBUTING stay on github and we introduce dedicated pages for the website under docs
Lee Surprenant (Nov 08 2019 at 20:28):
i opened https://github.com/IBM/FHIR/pull/393 to fix the broken link by removing CONTRIBUTING from the site. now the github repo is the only source of truth for that info.
Last updated: Apr 12 2022 at 19:14 UTC
