In this thread I propose a couple of things and outline my plans for writing content on TWHL.
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 code and 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 beginners

What 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 problem

Now 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 solution

We 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 writing

Oh 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 improvement

Here 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

Generally speaking, I'd also add a bunch of 2D illustrations everywhere. These tutorials were written back in the day when pictures were... mmm... very expensive. Not so much nowadays. My tutorials tend to be littered with screenshots and illustrations, often a bit too much even.

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

Penultimately, a whole lot of tutorials are prefixed with 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

Of course, it is possible to just keep them as-is and nobody will probably care. (except me of course, but I'm hypersensitive to details)

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.

For pages in category:Entity Flags, we should either:

• add to the title, in parentheses, the base class or entity it applies to, OR
• put them into subcategories with the same info

so you can know that from a glance at the category page instead of having to click on every single page – a problem that would get worse as more pages are added.

I am not sure if the Entity Flags category needs further categorisation. I didn't even know it existed until you mentioned it.

The way I imagine it, someone would normally arrive to that page if they're looking for info about a specific entity flag, not to browse them, so, how much value would it really add?

Yeah, I think those flag descriptions should probably just be in the relevant entity pages, doesn't make a whole lot of sense to have separate ones. I think these came from the old glossary section from before we had a wiki.

I think the lists of attributes and flags in the entity guide are mostly based off of the official FGDs. Which is unfortunate because the FGDs are far from accurate. For example the "Not In Deathmatch" flag actually works on any entity regardless of game or mod, so it should probably be included in every entity page? But does it make sense to include a description of it on every page, when we might want to update that description some day?

I think the lists of attributes and flags in the entity guide are mostly based off of the official FGDs. Which is unfortunate because the FGDs are far from accurate. For example the "Not In Deathmatch" flag actually works on any entity regardless of game or mod, so it should probably be included in every entity page?

I share the same feeling as well about K/V pairs and spawnflags coming from the FGD rather than the game/mod's code. While this is inevitable for games/mods with closed source without reverse engineering (Counter-Strike: Condition Zero - Deleted Scenes and Team Fortress Classic for example), it would be best to rely on the game/mod's code whenever possible.

Sure, reading and understanding code is not everyone's forte but it's basically the truth when it comes to entity's configuration and behavior (that's how I discovered the differences between Half-Life/Deathmatch Classic/Ricochet for trigger_teleport). Non-programmers could always ask programmers to double-check or whatever if necessary (through live/Discord shoutboxes or forums).

Yeah, I think those flag descriptions should probably just be in the relevant entity pages, doesn't make a whole lot of sense to have separate ones. I think these came from the old glossary section from before we had a wiki.

I think this would make sense for "unique" K/V pairs and spawnflags that you would find in a single entity. I'm afraid it wouldn't work well for common K/V and spawnflags because it would be tedious (imagine duplicating and keeping consistency of the "Gag" spawnflag across all monsters entities for example).

But does it make sense to include a description of it on every page, when we might want to update that description some day?

That's one of the counter-argument of the point above.

If possible, I suggest to combine "the best of both worlds": have the ability to "inject" (or "include") a wiki page within another. For example: we could have a wiki page dedicated to that "Not in deathmatch" spawnflag with just the description and in the entity's page, we would just do something like [include=Spawnflag:Not in deathmatch]. The entity page would render the spawnflag page like if it was part of it's content. Need to update the description? Update the spawnflag page and it propagates automagically to all entities pages that uses it.

The inconvenient is that it would require Penguinboy to update the WikiCode parser and page rendering to add such feature (while making sure it's secured and doesn't inject anything "external").

Hm, that would be a bit tricky to add, other pages will have categories and other stuff that shouldn't be included in the base page, also there's the challenge of what you do when the embedded page is updated... then you have to detect and re-render all the pages that embed it. I think I'd need more of a justification for a feature like that.

I tried out a multi-column layout to emulate an infobox-style panel at Entity Flag: Not solid/Passable. Check them out and comments welcomed.

Hm, that would be a bit tricky to add, other pages will have categories and other stuff that shouldn't be included in the base page, also there's the challenge of what you do when the embedded page is updated... then you have to detect and re-render all the pages that embed it. I think I'd need more of a justification for a feature like that.

Hm, I wonder how MediaWiki, the workhorse for Wikipedia, manages it. It's unfathomable that they could have something like a templating system in place, with exclude and only-include sections... But what do I know about these stuffs, amirite? ¯\_(ツ)_/¯

It's a lot of work, that's all. The work Dan does on this site is unpaid, so let's keep our expectations and sarcasm in check.

We added a new section on the website's main page to make the wiki more visible. It should help people find it and get started.

I also cleaned up some entity guide pages for entities but there is a lot more work needed there.

I've got some notes on what needs to be improved:

In general: prefer existing documentation (e.g. Microsoft website resources that explain a feature are sufficient)

• Make the wiki more visible. The recent addition to the main page helps but users should be drawn to it as much as possible.
• Update tutorials for modern tools, try to condense information that is spread across multiple pages. E.g. there are several wiki pages that cover leaks, merging them and streamlining the information will go a lot further to help.
• Rewrite tutorials to use third person perspective (i.e. no "i" or personal anecdotes).
• A page that covers the essentials of using a PC. Things like using Windows Explorer, configuring it to always show file extensions, using the command line, using Windows Search, using Google Search with filters. Web browsers plus recommended add-ons (UBlock Origin at minimum). This page should bring users up to an expected base knowledge level for other tutorials. Some of this stuff is likely overkill for most people but it's better to establish the expected skill level up front.
• A list of programs that are recommended for use:
  • Notepad++ for general purpose text editing
  • Visual Studio Code for various programming and scripting languages
  • Visual Studio Community for C++ use and Half-Life modding
  • WinMerge for finding differences between text files and directories
  • Irfanview and GIMP for viewing and editing images
  • GoldWave for audio editing (cue points specifically)
  • Audacity for general audio editing
  • Hex editor for viewing and editing binary files (personally use HxD, may be outdated, need suggestions)
  • OBS for video recording
  • Kdenlive for video editing
  • Blender for modeling
  • SourceTree for Git GUI (alternatively Github Desktop)
  • JACK for mapping (Trenchbroom HL support is getting good as well)
  • Half-Life Asset Manager for model viewing and editing
  • Paranoia 2 Model Viewer for Xash models and as an alternate model viewer
  • Virtualbox for running virtual machines (useful for Linux development on Windows)
  • Putty for connecting to servers over SSH
• List of programs that are NOT recommended for use:
  • Hammer (outdated, buggy)
  • Milkshape 3D (outdated, hard to use and lacking in modern tool support)
  • Jed's Model Viewer (buggy, limited, replaced by better alternatives)
• A page that explains how to use the search function in various commonly used programs (cover regular expressions in particular):
  • Notepad++: CTRL+F
  • Visual Studio:
    • Explain what Intellisense is
    • CTRL+SHIFT+F, explain the various options
    • Peek Definition
    • Go To Definition
    • Go To Declaration
    • Find All References (not always 100% accurate due to C++ language complexity confusing Intellisense)
    • View Call Hierarchy
    • Visual Studio Search (search entire IDE): CTRL+Q (https://learn.microsoft.com/en-us/visualstudio/ide/visual-studio-search?view=vs-2022)
  • Github: search in repository, explain filters including negation with particular emphasis on path filtering (e.g. -path:tests filters out results in the tests directory)
  • Explain how to search for compiler errors (e.g. site:learn.microsoft.com C<error code> or LNK<error code>)
• A page that explains how to use Git effectively:
  • Cloning
  • Creating local repository
  • Checking out branches
  • Merging, pulling, pushing, fetching, rebasing, stashing
  • Importance of committing changes, descriptive commit messages, how and when to use soft and hard reset
  • Prefer use of a GUI like SourceTree over the command line
• Instill a proactive mentality: search first using the various search tools available, check tutorials and documentation (e.g. TWHL wiki), try to solve a problem before asking for help. Explain importance of trying yourself (experience gained is more valuable than anything, allows for improved problem solving over time)
• Explain importance of learning C++ before trying to make a mod. Many beginners underestimate the difficulty in making a mod without having requisite knowledge of the language and assume copy pasting code is sufficient. The average beginner needs several months of experience before they can realistically make a mod. Though copy pasting may work for some cases it will fail for anything that involves copy pasting externally visible symbols like non-static free functions. Explain how differences between mods can make copy pasting difficult to impossible and requires knowledge of the language to modify code.
• List of common compiler errors categorized by compiler (MSVC, GCC, Clang) and by compiler step (compiler itself, then linker, many commonly reported errors are linker errors)
• List of errors shown by the game categorized by type (host error, sys (fatal) error, errors logged in console), include error message template and example as well as common errors if relevant
• Explain how to debug errors using qconsole.log
• Explain how to debug crashes (using qconsole.log, debuggers)
• Explain the concept of remote procedure calls and show how events and user messages are primitive implementations of the concept

"Rewrite tutorials to use third person perspective (i.e. no "i" or personal anecdotes)."

Disagree. Reading tutorials can be fun, it's a great thing. But if you do that, then remove the original author's name, because it's not their tutorial anymore.

Since anyone can make improvements to tutorials today, I think it makes sense to move away from the first person perspective - there is no "I" in a tutorial written by many - and to remove any signatures and instead use the "credit" tag: [credit:Original author|user:1267]

Tutorials can be fun in 3rd person too. For TWHL's books (e.g. the programming series), a 3rd-person style without too much "fun" is a must, because it certainly is authored by several people (Penguinboy, Solokiller, Shepard, me, etc.) and must be consistent.

On the other hand, for guides (esp. series of guides) written solely by a single person, I think 1st-person is acceptable (but you don't want it to be strong). Realistically, it's not like someone's gonna edit a huge chunk of the guide, usually it's just minor improvements like correcting typos, grammar, or some numbers. I will admit I am a little biased, I like seeing personality in tutorials, and I'm particularly guilty of it myself, having written quite a few with lots of... personal touches.

But honestly, if you think about it, people visiting TWHL absolutely don't care who wrote the tutorial - they're interested in the tutorials, not the authors. If they're reading it for recreational purposes or for fun, then yeah, personality is cool. But most people are just looking for explanations and step-by-step guides, so having consistency in writing would be good to have. Having a pretty different writing style in each tutorial would break this consistency a lot.

In conclusion, I honestly dunno, I'd like to have 1st-person but at the same time, it has some side effects I briefly mentioned up there.
If someone really cares a lot about personality/fun and wants to read stuff from a specific author because they're fun to read, there are websites like Medium, where you can write about anything and in any way, within reason that is. That's my take on it.
(obviously, nobody here writes on Medium, but it could be anything really, e.g. I make video tutorials on YT)

The tutorials on this site are hosted on the wiki. Wikis are collaborative, so tutorials aren't going to be written entirely by a single person.

A lot of the articles we've got are old and outdated and need reviewing and improving. They also need to be condensed and combined, like for example we have too many articles on leaks:
https://twhl.info/wiki/page/Leak
https://twhl.info/wiki/page/RUST%3A_Ways_to_Prevent_Leaks
https://twhl.info/wiki/page/RUST%3A_Big_Block_Method_of_Error_Finding
https://twhl.info/wiki/page/Tutorial%3A_Diagnosing_Problems
https://twhl.info/wiki/page/Tutorial%3A_How_to_fix_those_leaks

Not all articles are purely about leaks but there is redundant information here. Ideally only one page would cover the subject, linked from anywhere else that it's mentioned. The page format should be clear and straightforward:

What are leaks, what causes them

Compile tools require maps to be sealed because...

How to find the cause of a leak

Point files, any notes about loading them in various map editors

How to prevent leaks from occurring

Best practices

Examples of leaks

General case: map is visibly not sealed
Less general case: a brush entity is used to seal the map, special mention to func_detail not sealing maps
Off-grid brushwork
Complex geometry causing leaks due to precision errors converting data

More generally we should add more information on the main wiki page to explain that there are Half-Life 1 and Half-Life 2 modding tutorials, what the differences are and what to expect.

The main page for each engine should then have a list of each modding category along with a short description. Currently these pages rely on wiki categories to provide this information and it's confusing to newcomers.

The Valve Developer Community does this: https://developer.valvesoftware.com/wiki/SDK_DocsEach of those categories should then have a page that covers the subject in more detail, along with a list of tutorials. Ideally tutorials would be split into 2 lists: ones that are known to be up-to-date and relevant and archived ones that are outdated, possibly referencing obsolete tools or older methods.

This keeps the older tutorials around without confusing people as to whether they're applicable or not.

Each category should also have an "introduction to <category>" tutorial to explain the basics.

Some information that definitely needs to be there is:

• Warning against the use of older tools like Jed's Model Viewer, Milkshape 3D, Hammer. People still use these even though they're old and obsolete. We should find out where they're getting these from to ensure that they're not getting bad advice right out of the gate.
• Making sure that people understand what it means to make a mod using the source code. C++ is one of the hardest languages out there, copy pasting stuff isn't going to work for anything beyond the simplest of changes. Unfortunately people seem to think that this is like copying configuration files or scripts that are loaded in isolation by the game, which don't have to deal with the many rules that C++ has. A basic understanding of computer programming is essential to learn to modify the source code, at the very least knowing variables, functions, types and the concept of function calls, as well as understanding how header and source files work is needed to do common tasks like making a modified version of an NPC or weapon. We should find good tutorials that explain these things to make that easier to do.
• Link to existing documentation like JACK's manual.
• Properly explain how to set up JACK for mapping, ensure things like getting up-to-date compile tools and setting them up correctly is covered. We've seen some people using outdated compilers as well as running tools in the wrong order.
• See my previous post for a lot more of this.

We should also add a page explaining how the engine works, its architecture, where it looks for stuff, engine limits and which ones can be changed (and why others can't be).

I'd like to take a crack at this but i'm preoccupied with other projects. If anybody wants to write these i can put together a cliff notes version of these, maybe add barebones pages without formatting but otherwise if i can find the time i'll do it myself.

Some easy work that can be done is to deal with the pages that require review: https://twhl.info/wiki/page/category%3AEntity_Guides%2BReview_Required

I've already reviewed some entity pages, you can look at this one for an example on how to update those: https://twhl.info/wiki/page/func_button

Specifically the header is what needed updating in most cases. Some entities also listed keyvalues with options that didn't apply to them, specifically sound options where the user was told to figure out which ones were relevant. I removed the unused ones and updated the others with sound and sentence names.

I don't know what the plan is with regards to the Team Fortress Classic versions which are listed on the same page. Those could be separated out or merged using the same approach as what's done on the VDC. Here's an example: https://developer.valvesoftware.com/wiki/Func_button

This is a fair amount of work, best done in stages (fix header formatting and irrelevant content issues first, then reformat). Figuring out how to structure the information and indicate game-specific features should be done before making any changes.

It would probably help to make a dedicated page for the entity list, just like the VDC does it: https://developer.valvesoftware.com/wiki/List_of_entities

This is more organized and easier to search through, and we can add information here that a category won't allow for.

Does that sound good?

I'm loving this.

The RUST & VERC articles are archives, so I think those should be kept as-is.
TWHL's own guides, however, should definitely have redundancies taken care of. I believe what we have now is, simply, a consequence of transitioning from TWHL's legacy article-writing format to a wiki format, and so long as we have this, the transition isn't 100% complete.

Properly explain how to set up JACK for mapping, ensure things like getting up-to-date compile tools [...]

For years I wanted to rewrite "In the beginning" and basically update a buncha mapping guides into a modern context. I think I could attempt something soon enough.

Ideally tutorials would be split into 2 lists: ones that are known to be up-to-date and relevant and archived ones that are outdated, possibly referencing obsolete tools or older methods.

I agree, it would be nice to categorise those.

Oh snap, it's been a while. This month I'm planning to write a couple articles regarding TrenchBroom:

• Setting up TrenchBroom
• TrenchBroom Half-Life support report

One is to address the problem newcomers face when trying to set up Half-Life with TrenchBroom. J.A.C.K. provides an automatic game configuration for Half-Life when you give it the HL executable path, with various built-in compile configs too.

In the other, I'll be defining what it exactly means to "support Half-Life", i.e. what features or mechanisms an editor needs to have. I've also been thinking of alternatives for this one: "Transitioning from J.A.C.K. to TrenchBroom", "Differences between J.A.C.K. and TrenchBroom", "Hammer vs. J.A.C.K. vs. TrenchBroom". Some may want a unified list of all relevant map editors to be compared, I'd like to focus on just two-three main players in the community.

Next month, I'd be looking to take care of some "review required" pages (or maybe even this month) and renew some guides. I'd like to rewrite "In the beginning" in a modern context, using J.A.C.K. and VHLT,

I've split the tutorial for setting up a mod directory into WON and Steam versions and i've added links to the main tutorials page to point to these tutorials: https://twhl.info/wiki/page/category%3AGoldsource_Tutorials

I've also added some extra info about the use of unrelated client and server dlls and changes in how the game uses the multiplayer_only option.

The tutorial for setting up level changes has been updated to cover a common issue where level changes break if set up incorrectly: https://twhl.info/wiki/page/Tutorial%3A_Changing_Levels

This information was missing and it often happens to beginners so this should help.

The Half-Life Programming - Getting Started tutorial has been updated to streamline the tutorial and remove obsolete information.

References to Mac development have been removed. Half-Life Updated no longer supports Mac builds and only the Steam version of Half-Life has a Mac version.

Steam will drop support for the last 32 bit Mac OS version in a few years, they dropped support for Mac OS 10.12 this last september and the last 32 bit version is MacOS Mojave (10.14). This is in response to Chromium dropping support for those versions since Steam uses Chromium for its user interface.

Chromium is dropping support for MacOS Mojave in their latest versions, as noted in this issue which tracks removal of code used to support older MacOS versions.

Chromium version M117 released a few months ago. Steam usually trails behind Chromium updates and will be updating to a version that no longer supports Windows 7 and 8.1 at the start of next year. Chromium M110 was the first version to drop support for those and released about a year ago.

Given the rate at which Steam updates its Chromium dependency it will likely drop support within 1-2 years.

I’m joining late in the discussion, so bear with me if I say something already mentionned. I read the posts but I might have missed something.

I learned mapping at an age where I barely knew how to use a computer. When I was told to go in the "File" menu I was looking for it in the Windows XP’s Start Menu, I didn’t understand what the tutorial mean by "extracting" something, and it took me years to understand I had to compile a map to play it and figure out that to create a mod I was supposed to edit "liblist.gam".

The TWHL wiki is a great source of information, but as I think was already mentionned, it looks absolutely daunting to me and to any real beginner.

I believe it is crucial to have clear distinction between an all-encompassing introductory tutorial for complete beginners that assume no previous knowledge, and more specialised guides and other specialised articles like glossaries and entity references. This would help beginners know where to start, and more advanced modders know where to find the information they are looking for.

This distinction must be made clear in the wiki homepage (by displaying a visible link to the introductory tutorial). The current wiki homepage simply lists articles which would seem extremely confusing to any beginners. For instance, after being scared by the sheer number of available pages, they would click on "Tools" as advised, and find an enormous number of things they are supposed to download, not knowing what they do.

In specialised articles, it would be great to display a small banner warning readers that it requires some skills and redirecting beginners to the introductory tutorial). This might sound overkill, but for the minority of confused beginners I think that will be very useful, and it does not need to take a lot of space.

For me, most of the effort needs to go in the introductory tutorial.

The introductory tutorial

I believe tutorial, to mean an article that explains and teaches modding from the very beginning, is an appropriate term, moreso that guide and especially explanation. Guide to me seems more appropriate for more advanced articles on specific techniques.

The situation is very difficult for a beginner arriving on TWHL. For instance, assuming a beginner manages to access the GoldSource tutorials homepage, they might not know what GoldSource really is, what is WON, what is modding. Maybe they’ll think they have to first do the "modding in general" section, then learn programming, to finally be able to reach the part about level design. They will also be discouraged if they see the sheer amount of pages in the category at the bottom of the page, not knowing they do not need to read all of them. Even if they get to Introduction to mapping, the introduction is very thin. What does the tutorial explain? What is a level editor? Maybe the user expects the level editor to be in-game as it is for other games.

Content

That’s why we need a real introductory tutorial that would be all-encompassing and aimed at beginners (e.g. "Learn to create maps and mods for Half-Life 1 games"). This introductory tutorial would start by explaining for what games the tutorial is for (Half-Life 1, CS, Sven Co-op, etc.), what GoldSource is and why modding is similar on all GoldSource games, what modding is, and what can be done (creating maps, mods, etc.).

It would then link to the mapping tutorial (e.g. "Learn to create maps for Half-Life / GoldSource games and mods"), explaining what it will allow the reader to do. It would also link to the programming tutorial, warning that it requires C++ knowledge.

At least for the mapping tutorial, any IT skills such as extracting a zip file or installing a program should be explained. It doesn’t take too long, especially with one or two screenshots. Having a page that covers the essentials of using a PC, might be useful Solo, but it’s best to include its relevant content directly in the beginner tutorial (it will be easier to understand and apply), instead of relying on it as a requirement. Similarly, a very small introduction to GoldSource, describing it as a collection of files that allow Half-Life and its mods to run and handle its graphics, audio, and AI is sufficient, instead of a full-blown article on the subject (for the beginner tutorial at least).

Mabe this is what you mean by the "in the beginning" tutorial that you intend to create Admer? I think it would be amazing to have such a tutorial.

Navigation

The current wiki navigation can suit specialised articles, but it should be made simpler and more straigtforward for beginner tutorials. The tutorial starting point page should list all pages of the tutorial, and only those links, so as not to confuse or discourage the read. Each page should link to the next and previous chapter, as well as to the starting point page. This could be done in the website’s code or, more probably, directly in the article content.

Example

So, in the end, for the introductory tutorial, we might have something like this:

Learn how to create maps and mods for Half-Life 1 and GoldSource games (the introductory tutorial)
- What games is this tutorial for: HL, CS, SC…, what is GoldSource, what is modding, how to learn mapping (link to tutorial)
- Screenshots / links to maps & mods created by the community, for illustration
- Link to navigate to the mapping tutorial
- Link to navigate to the programming tutorial

Learn how to create maps for GoldSource games (the mapping tutorial)
- Link to the parent tutorial (the introductory tutorial)
- What is mapping, examples of maps, etc.
- Link to the next chapter: "Installing the map editor"
- List of all the chapters of the tutorial

Installing the map editor
- Link to the parent tutorial (the mapping tutorial)
- Why you need to download a map editor
- How to download and install a map editor
- Link to the next chapter (setting up the map editor)

Specialised articles

By specialised articles, I mean any article that only address a specific topic and requires some previous knowledge, which is what the current wiki mostly contains. I think the main issue is with the navigation that should be improved, maybe by improving navigation between categories, maybe by making navigation more hierarchical (displaying only the top categories in the homepage), and moving the list of all pages of the category in a separate page, maybe in the results of a search request).

Yeah we really need better beginner tutorials, the problem is that nobody has time to write all of that down. And any tutorial that explains everything people need to know will end up being very long due to how many terms there are, the amount of history, etc.

I thought about making pages that list every kind of fatal error the engine can produce along with an explanation (easy enough to find by searching for Sys_Error calls and Host_Error calls using a disassembler) but that also takes time.

Also needed is a page containing all of the old update notes from the pre-Steam HL website and the old Steampowered news site before they switched to Steampipe since that's all lost now outside of archive.org, but again that takes time to dig through and assemble. There's also information in the old mailing lists that isn't documented anywhere else.

Yeah we really need better beginner tutorials, the problem is that nobody has time to write all of that down. And any tutorial that explains everything people need to know will end up being very long due to how many terms there are, the amount of history, etc.

For now we really just need a starting point for beginners, not to make it comprehensive. I could work on it, but we would need to decide how it will relate to existing beginner tutorials and to Admer’s planned tutorial.

I'm down for writing a number of beginner tutorials. I could allocate some time to write them all by New Year, just need a bit of a plan first.

Yeah, we could make a plan on a Google docs with a hierarchical structure and the possibility to add comments. I can create it if that suits you.

I know this hasnt eeally been active, but I would write some tutorials for hammertime or trenchbroom, hammertime is a fork of sledge which is supposed to be as similar to base hammer as possible

TrenchBroom stuff is in my plans. Hammertime will be interesting to see.

Hammertime is like normal hammer, although a bit more modern, I would if you want ofcourse, include some articles for some Stuff about Hammertime