In short, I am looking to improve navigation for the Wiki articles, establish some sort of guidelines for writing and see what needs to be done regarding introductory guides. Generally, the goal is to make stuff more accessible to beginners. Hopefully we'll get some conversation started.
You all know me, but here's a quick introduction:
I've been writing tutorials for 6 years now, having started writing on GameBanana (please don't look at them lol, especially the first ones), and I found TWHL to be a pretty nice place for that, so I switched to writing here around 2019 or so, and I've been here since 2016 for sure. I am primarily interested in writing mapping and programming tutorials, beginner and advanced ones alike, I just love writing.
Now, here's the thing. This place is pretty nice from the writer's POV (aside from the occasional parser edge case with
inline codeand so on), and it's pretty nice for long-time members. But I think we can improve the landing a little bit, for beginners that is.
Improved navigation for beginnersWhat I'm about to say involves a fair bit of assumptions, so take it with a grain of salt.
Let's look at the index page for GoldSRC tutorials: On first glance, this is probably perfectly okay. You got a couple of introductory articles highlighted on the top, and then some subcategories to filter out stuff you don't need. Currently we have 22 mapping tutorials in the beginner category. This is very nice. Let's put ourselves into the perspective of an absolute beginner mapper, who maybe hadn't seen Dimbeak's mapping videos and is coming here. There's a chance they'd navigate here: Just for a second, imagine you know next to nothing about Hammer, or BSP, or carving, or anything like that.
The problemNow which one of these is relevant to you?
"Introduction to mapping" outlines a bunch of fundamental definitions, but you don't know that yet.
"In the beginning" shows how to create a bunch of different stuff, and because it has multiple parts, you may potentially be turned off by it, thinking it's mega long and complex, like some 30-minute video tutorials. Of course, it depends on the type of person. In reality, it's a series of short, level-headed guides.
(Let's also temporarily ignore the fact that a lot of tutorials involve setting up ancient tools, I'll talk about this in the next section)
The solutionWe need something that will almost instantly catch the reader's attention and let them know "yeah, this is exactly what you gotta read".
I'm not a marketing guy, so I can't catch attention all that well, but this is my idea: I published this change today, on the 1st of September 2022, and I am hoping to coordinate future changes like this here. Feedback is well appreciated.
I think this is an improvement because 1) there are now a few concept explanations as well as a troubleshooting guide upfront, and 2) each guide has a brief description next to it. I tried to keep them mostly short. They have an extra chance of helping the reader find the right place to start.
I was also thinking of this design, basically a grid with recommended articles with brief descriptions: On the left side, you have guides for newcomers, and on the right side, I am honestly not entirely sure. I think we can include some in-depth technical explanation guides there, or some interesting advanced tutorials. Tell me what you think!
Guidelines for writingOh boy. Ooooooh boy. I'm guilty of this one sort of.
For the sake of consistency, it would be pretty nice to have a couple of guides for contributors/writers. I love high-quality, consistent writing and would love to see that on TWHL. The Programming book is an example of high-quality writing, I like it (I mean, I wrote a chunk of it so I'm biased).
However, I've noticed one lil thing: the parts I wrote are more subjective (1st-person singular is not seldom), the parts by Penguinboy are more objective but both styles still have a pinch of personality, especially Shepard's contributions. Maybe I'm overthinking, but it would be nice to outline the basic style for the books.
Modernisation and quality improvementHere I'll outline some articles I'll write a modern equivalent of, or improve in some other way.
- Tutorial: In the Beginning series - I plan to write a new In the Beginning with J.A.C.K. in mind, and maybe a sister series for TrenchBroom
- Tutorial: Compiling Introduced - this is a fine, fine article. I think it might benefit from a bit better formatting though
- Tutorial: Diagnosing Problems - as usual, fine article, but can benefit from some modernisation. Personally I'd also reword it so it's a bit more objective
- Tutorial: Dimensions - could use some illustrations
Also, here are some brand new articles I wanna write, other than tutorials I typically tend to write:
- TrenchBroom configuration guide for GoldSRC
- Guides for Linux?
- Detailed in-depth explanation of BSP and the entire compilation process
Tutorial:. However, my interpretation of "tutorial" is that it's a how-to. A chunk of them are what-is, if you get what I mean. Penguinboy suggested "Guide" on Discord, and I came up with "Explanation" a year ago when I wrote about the reason why brushes can't be concave.
So, what I'm saying is, maybe it'd be helpful to separate how-to guides and explanations of things. Explanations don't fit Definitions nor Tutorials the way I see it. Here are some articles that I think can potentially fit the Explanation prefix:
- Tutorial: Dimensions - this one is not an explanation per se, so it might be better to come up with an alternative name
- Tutorial: Introduction to mapping - this presents some theory, no how-to in it really
- Tutorial: All about info_nodes - same as above, definitely a good candidate for explanation articles
- Tutorial: Render Properties - yep, though this one could be part of Definitions
Finally, what do you think about linking keywords to their respective Definitions page? E.g. a beginner tutorial might mention ORIGIN, and I think it'd be useful to link to it, in case a newcomer doesn't know, they could simply click on it to see.
It'd look something like this:
"Make sure to give the door an origin brush."
Also, just to make sure, I plan to do most, if not all of these changes. This thread is more for me to see what the community thinks about it, but if we manage to get extra volunteers, that'd be epic.