search

rog-golang-buddies / golang-template-repository

Kickstarter repository for a golang service
Apache License 2.0
17 stars 7 forks source link

Use internal links in README to quickstart and other docs #72

Closed hansvb closed 2 years ago

hansvb commented 2 years ago

GitHub supports internal links in markdown-files. Why not use it? Also because there is still a link to the published documentation, there is the risk of this documentation is not up-to-date with the current state of the repo.

hansvb commented 2 years ago

I was doing some changes and then reverting them back in another commit so I guess it's better to just close this PR and solve the problem elsewhere. It's just that it is a bit inconsistent to both link to documents internally and link to documentation to the published site. Why does everyone have to have the documentation locally in own repo? (+) would be that the documentation is up-to-date with the version of the template but (-) is possible inconsistencies between template-versions. Maybe the documentation should just be a different repo all together? (Separate from the template-repo?)

Anyway feel free to close in stead of merge.

haani-niyaz commented 2 years ago

@hansvb addressing your concerns.

there is the risk of this documentation is not up-to-date with the current state of the repo.

Firstly, the link to the published docs is provided in the event you are unable to see your published site as it provides the same info. That section (in the README) is also meant to be deleted in favour of your repo's README on initial setup.

The template repo changes along with the docs are all meant to be reviewed and periodically added to your repo. There are no template repo specific docs, they are relevant to your repo to aid you to get familiar with the CI configuration.

GitHub supports internal links in markdown-files. Why not use it?

As explained above, the intention is not to refer to the template repo links but to your own repo's Github pages site.

Why does everyone have to have the documentation locally in own repo?

The purpose of this is to keep your docs closer to the code and in version control. The closer it is to you, to your codebase, the more likely you are to update it and have access to it locally.

(+) would be that the documentation is up-to-date with the version of the template but

As previously stated the docs you get from the template repo is relevant information for you to understand and manage your CI configuration.

(-) is possible inconsistencies between template-versions.

It will only be inconsistent if you fetch changes from the template repo and omit the docs. For instance, when you use the template repo to create your repo, it is a point in time snapshot. You can optionally synchronise with the template repo which will provide you with the next complete set of changes unless you explicitly don't include it.

Hope that clears it up. I'll close this for now.