zaphosting / docs

Our ZAP-Hosting Community Guides
https://zap-hosting.com/guides
19 stars 65 forks source link

header improvements #1325

Closed Blumlaut closed 2 months ago

Blumlaut commented 2 months ago

This PR is in meant as a "Working Example" of my suggestion on clickup to standardize the headers in all of our docs, i have removed any "Step", "Schritt" texts from the titles and have properly nested them so they (should) be easy to understand, for example, if a guide explains a program and then tells you how to install it, all install steps will be under the "Installation" header (or however it's called)

If these changes are according to your liking i can continue applying them, i have a lot more files stashed (around ~50) that i havent committed yet as i havent had time to properly redo them yet.

github-actions[bot] commented 2 months ago

badge

Build Successful! You can find a link to the downloadable artifact below.

Name Link
Commit e3147749ad2294113f0af696a8d59d24873c7666
Logs https://github.com/zaphosting/docs/actions/runs/10974874263
Download https://github.com/zaphosting/docs/suites/28680062997/artifacts/
ThatGuyJacobee commented 2 months ago

Hey, I think removing the "Step X" phrases is a good idea, it saves space on the right-hand side. Plus we can adapt our guidelines in regards to headings and keep it under one standard format, essentially phasing out the whole "step-by-step" heading idea.

Not sure about a few of the Hx Tag changes, specifically ones where many H3's are nested into a H2. Although this is not the worst thing in the world, can easily be tweaked and separated into better sections where needed (might also just be a me thing). Overall, looks good.

Blumlaut commented 2 months ago

Not sure about a few of the Hx Tag changes, specifically ones where many H3's are nested into a H2. Although this is not the worst thing in the world, can easily be tweaked and separated into better sections where needed (might also just be a me thing). Overall, looks good.

My main thought with this was that we should encourage "intuitive" navigation, for example, when a guide is structured like this

Introduction
Guide Part 1
Guide Part 2
Guide Part 3
Conclusion

it should be obvious that Guide Part 1-3 belong together, so when installing software, it should look "roughly" like this:

# Introduction
# Installation
## Installation Part 1
## Installation Part 2
## Installation Part 3
# Conclusion

My PR was mostly created in a hurry so it does not get this point across properly, but i hope this helps get my idea across @ThatGuyJacobee

fgalz commented 2 months ago

We already wrote in Slack and I agree on some points that this is not the best solution. I've already texted with Jacob and we'll have another chat about how exactly we're going to proceed here.👍