Merge content under (JavaScript, CSS) directories into single pages

18F / development-guide

A set of guidelines and best practices for an awesome software engineering team

https://engineering.18f.gov

Other

1.25k stars 122 forks source link

Merge content under (JavaScript, CSS) directories into single pages #235

Closed Sgtpluck closed 3 years ago

Sgtpluck commented 3 years ago

Addresses #199.

Uses include_relative to avoid having to actually cop/paste everything in.
Cleaned up a couple things in the JavaScript docs but didn't go too wild about it as these pages need more ❤️ than is in scope.
Added a list of topics at the top to make the pages more navigable -- curious if there should also be some anchor links that toggle back up to the top under each topic.

ryanhofdotgov commented 3 years ago

Cool! A couple of quick thoughts:

Unfortunately, the include_relative paradigm breaks the "Edit this page" model that's part of most TTS handbooks. Try out the corresponding, bottom right link that should be on every engineering practices guide page to see how that workflow goes.
There's a built-in uswds-jekyll mechanism for intra-page subsections that could replace (or augment) your top level links. Checkout the Code Review page for an example.

Sgtpluck commented 3 years ago

😭 😭 okay i will make them one long page. thanks for the intra page subsections tip, that looks much nicer

Sgtpluck commented 3 years ago

@ryanhofdotgov this look better? thanks for the review!

ryanhofdotgov commented 3 years ago

👍 – the one remaining thing I'd recommend is to add redirects for the pages you're deleting.

Here's the docs for jekyll-redirect-from and an example in this guide. Under this approach, the JavaScript and CSS pages would each have ~10 entries under redirect_from in its Jekyll front matter.

Last year I did some minor reorganization of the website, without setting up a redirect, and I promptly got a ticket opened by someone working at a public library 😁. It also gives the search engines some time to catch up to the new site structure.

Sgtpluck commented 3 years ago

whew that's one way to get some user feedback @ryanhofdotgov! thanks for the tip, that's really smart.