search

ministryofjustice / justice-gov-uk

Justice UK website
https://www.justice.gov.uk/
MIT License
2 stars 0 forks source link

User docs for editors #207

Closed EarthlingDavey closed 4 months ago

EarthlingDavey commented 4 months ago

Hey @EmilyHazlehurst , would you mind reviewing when you have time please?

HTML view is at: https://github.com/ministryofjustice/justice-gov-uk/tree/user-docs/user-docs

This is a draft PR because IDK if it's best to have the .md docs in the repo, or have the content in WordPress only.

wilson1000 commented 4 months ago

Hi @EarthlingDavey, we can use GitHub Pages to publish the docs. We can add style later if we want to.

We configure the page here: https://github.com/ministryofjustice/justice-gov-uk/settings/pages

EmilyHazlehurst commented 4 months ago

@EarthlingDavey, in fact it might be easier for you to publish the docs and I can review them once they're published and finished. That way I'm not adding loads of comments about screenshots, because I saw that in your comment to Deepika you've not added them yet.

From a code perspective it all looks good though :)

EarthlingDavey commented 4 months ago

Hey @EmilyHazlehurst , thanks for the review! Sorry for butchering it 😅

I can at least address your points, publish and then ask for another review. Cheers!

EmilyHazlehurst commented 4 months ago

@EarthlingDavey @wilson1000 Just a thought, but could these be added to the wiki in a user guide section? https://github.com/ministryofjustice/justice-gov-uk/wiki/Documentation

That way we don't have to push code every time there's an update.

EarthlingDavey commented 4 months ago

Hey @EmilyHazlehurst , the wiki does sound like a good option.

For the time being, I'm finding it pretty easy (and enjoyable DX) to edit locally and see the html (hot reloading) in the browser.

There's a couple of other things to consider like: GH pages allowing for branding and a custom domain.

I'll get the content finished then we discuss which way will work best.

wilson1000 commented 4 months ago

Just a thought, but could these be added to the wiki in a user guide section?

Hey @EmilyHazlehurst we spoke about this when Davey was at lunch 😄 ... to summarise @EarthlingDavey; GH Pages is the better solution for user docs as this allows us to detach stakeholder support from technical, and we can style a GH Page. We also discussed putting the docs into a dedicated branch called gh-pages so we don't keep triggering a deployment build in the main workflow. What do you think?

EarthlingDavey commented 4 months ago

@EmilyHazlehurst & @wilson1000 thanks for the review!

I've merged this, even though I still have a bit left to do. It's a good oportunity for me to see ho the gh-pages workflow works (or doesn't 😀).

Re: a gh-pages it sounds like a good shout, but maybe it won't be needed in the future as bulk doc writing like this PR wont happen.