Refactor README and split long documentation out #235
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The README has grown a lot over time, making it harder to read. And as a single page adding additional doc only adds to the problem. Split specific doc sections out into their own directory, for clarity. This is a convention used on GOV.UK projects and encouraged in the README styleguide: https://github.com/alphagov/styleguides/blob/master/use-of-READMEs.md I've done this now because I want to add more detailed documentation on the publishing process, and document how to fix missing published packages, which is likely to be super long. Hopefully this will encourage more detailed documentation on the repo in general.
- Provide more detail on how to run tests, so hopefully people do - Update the inaccurate versioning advice and describe how we do version bumps now. It could still be improved a bit, but it's an improvement over what we had before. - Fix some types/copy-paste-errors.
| @@ -1,8 +1,11 @@ | |||
| # GovukTemplate | |||
| # GOV.UK Template | |||
|
|
|||
| This provides a template containing the GOV.UK header and footer, and associated assets. | |||
There was a problem hiding this comment.
This might be outside of the scope of this PR, but it would be good for the main readme to contain something about who template is for. It's not clear (to me) that this is outward facing for services rather than just for GDS use.
eg 'GOV.UK Template is meant for all services running under the service.gov.uk domain....'
There was a problem hiding this comment.
Absolutely agree. That, and quite a lot of other stuff, did feel out of scope though.
I'll steal/add your eg line though 👍
|
LGTM 👍 |
Moving packaging and publishing documentation to `docs` made it less clear how to consume `govuk_template`. Add links to the common ways to consume it. It's still not super clear, but I don't think the original was either. Ideally we should re-write the README/docs based on user needs of people using the packages, based on research
dsingleton
force-pushed
the
refactor-doc
branch
from
4fcf3a0 to
24c3732
Compare
|
Added @edwardhorsford's suggestion. Otherwise I think this is good to merge? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Move long
READMEsections todocs/directory and re-write theREADMEa bit.The
READMEhas grown a lot over time, making it harder to read. And as asingle page adding additional doc only adds to the problem.
Split specific doc sections out into their own directory, for clarity. This
is a convention used on GOV.UK projects and encouraged in the README
styleguide: https://github.com/alphagov/styleguides/blob/master/use-of-READMEs.md
I've done this now because I want to add more detailed documentation on the
publishing process, and document how to fix missing published packages, which
is likely to be super long.
Hopefully this will encourage more detailed documentation on the repo in general.