First draft for user guide PR #166
Conversation
- Still to be "ported" over and cleaned up from the PoC is the section on installing Java. - The FAQ also has some of the older content commented out with a planned return when brain starts working again properly. - Not all feedback has been acted on yet and one change in particular (on finding a terminal emulator-like app) could already benefit from being moved/refactored.
neoforged-pages-deployments
bot
deployed
to
neoforged-docs-previews (Preview)
Deploying with Cloudflare Pages
|
Changes: - Remove old `userguide/docs/faq.md.orig` - Remove extranous `.` at end of sentence in `userguide/docs/faq.mdx` - Attempt to improve wording of first section in `userguide/docs/java.mdx` - De-pluralise `applications` in `userguide/docs/java.mdx` - Add initial section on install headless server to `userguide/docs/installer.mdx`
neoforged-pages-deployments
bot
deployed
to
neoforged-docs-previews (Preview)
userguide/docs/java.mdx
Outdated
|
|
||
| To find out if you already have Java, you will need to locate and run the terminal application that is provided by your OS. | ||
|
|
||
| ### Location Terminal Application |
There was a problem hiding this comment.
It's probably best to specify that these are shells that come pre-installed with the OS. If the user decides to install their own shell, then it is up to them to know what the application is called.
There was a problem hiding this comment.
Good point. I'll clean that up 👍
| OpenJDK 64-Bit Server VM Temurin-21.0.4+7 (build 21.0.4+7-LTS, mixed mode, sharing) | ||
| ``` | ||
|
|
||
| ## Installing Java |
There was a problem hiding this comment.
I'm guessing something is supposed to be here? Usually, we recommend the OpenJDK provided by Microsoft as that is what is used by Minecraft. I think it's fine to list a few alternative JDKs as well for those who are adamant about remaining separate from that ecosystem, for one reason or another.
There was a problem hiding this comment.
Yep, my head wasn't working properly when I laid this out. I must've forgotten to paste a few paragraphs. I didn't realise MS has builds for more than just Windows but they're clearly listed at https://www.microsoft.com/openjdk - I'll fix up what I have in my notes to refer to that for all OSs, with Adoptium/Temurin linked for the non-MS JDK stalwarts, and get that committed soon.
|
Thanks for all the feedback. I'll get these bits addressed in my next commit. PS - Ive been squashing my commits to avoid all of you getting lots of noisy emails, rebuilds of the docs on Cloudflare, etc. If that's fine I'll carry on but let me know if smaller changes would be preferred. |
Changes: - Rename `*.mdx` to `*.md` where inline Javascript isn't used - Add missing `Installing Java` section to `userguide/docs/java.mdx` - Fix a few typos and try to reduce repition in various places - Add section on which version of Java to install to `userguide/docs/java.mdx` - Add section on installer log file to `userguide/docs/faq.md` - Reinstate and re-word commented-out section on driver troubleshooting in `userguide/docs/faq.md` - Add some inline HTML comments on things to consider documenting - Add initial article on launchers and mod managers - Various other little tweaks, because OCD...
|
I think I've addressed everything so far, but my brain's a bit foggy still so there's likely room for improvement still. If I have missed any of the requested changes, please let me know, it's definitely an oversight. Cheers! |
|
Apologies, but did you remember to push your commits? I haven't seen anything change since I last checked, and your previous comment suggested you addressed them. |
Bah. I did forget, sorry. Now pushed! |
neoforged-pages-deployments
bot
deployed
to
neoforged-docs-previews (Preview)
| ### NeoForge Installer Log File | ||
|
|
||
| When experiencing issues with the NeoForge installer, you might be asked to provide its log file, which should be created in the same directory the installer itself resides in. | ||
|
|
||
| For example, the installer for version `21.1.54` should create a file with the name of `neoforge-21.1.54-installer.jar.log`. |
There was a problem hiding this comment.
This feels oddly out of place. It should be prefaced on where the log file is used. For example, the log file indicates the steps NeoForge took to install, and asking for help anywhere will usually be followed by a question for the log file.
|
|
||
| First, check to see whether Minecraft without NeoForge works. If the game launches successfully and does not crash, read on. | ||
|
|
||
| If Minecraft by itself crashes, you will not be able to install NeoForge. |
There was a problem hiding this comment.
It might be best to redirect this to Mojang's FAQ or troubleshooting guide.
|
|
||
| Minecraft itself recommends the [Microsoft Build of OpenJDK] (Microsoft JDK) for running Minecraft. | ||
|
|
||
| <!-- With Windows being the common case, should there be a `WinGet` example? --> |
There was a problem hiding this comment.
I would not, as this is targeted at end users, not developers. Winget info would be more bloat than useful here. If there's people reading this documentation who really want to use Winget, then I think those people can be trusted with using Google for this information.
|
|
||
| You will need to install a specific version of Java depending on the version of NeoForge you are installing. | ||
|
|
||
| The following table lists the versions of Java that are recommended for a particular version of minecraft: |
There was a problem hiding this comment.
It's less recommended and more of the version you should be using when possible. While later versions are 'generally' backwards compatible, overloads or additional methods could unintentionally change the behavior. Though, I believe the last thing I remember specifically breaking was classloader stuff in J13 due to a new overload.
| - `logs` This directory contains log files for the game, with the files `latest.log` and `debug.log` being most pertinent. | ||
| - `crash-reports` This directory contains plain-text crash reports, each with timestamped filenames e.g. `crash-2024-08-11_15.54.06-client.txt`. | ||
|
|
||
| <!-- Not sure if the above list is the best way to format the info in it... --> |
There was a problem hiding this comment.
I would put more stock in the debug log as the latest log usually doesn't contain enough info. I don't believe we usually ask for the crash report file since it's in the debug log, but it's good to know about.
|
|
||
| <!-- Not sure if the above list is the best way to format the info in it... --> | ||
|
|
||
| ## Third-Party Launchers |
There was a problem hiding this comment.
Ok, not sure how much I support this section as it seems like we're giving recommendations on third party launchers. I don't find any major issue with it, but I'm not as well versed in launchers to determine whether they are not doing weird things with the access tokens or not.
I will defer this to @XFactHD and @IchHabeHunger54.
There was a problem hiding this comment.
Yeah, this was originally my idea, so I'll take care of this.
| <div class="col col--6" style={{padding: '10px'}}> | ||
| <Card | ||
| title="NeoForge User Guide" | ||
| body="Learn how to install NeoForge for both client and server, we well as some of the pitfalls you might experience along the way." |
There was a problem hiding this comment.
| body="Learn how to install NeoForge for both client and server, we well as some of the pitfalls you might experience along the way." | |
| body="Learn how to install NeoForge for both client and server, as well as some of the pitfalls you might experience along the way." |
|
|
||
| ## Prerequisites | ||
|
|
||
| In order to install Neoforge, you will first need to have Java installed on your computer. |
There was a problem hiding this comment.
| In order to install Neoforge, you will first need to have Java installed on your computer. | |
| In order to install NeoForge, you will first need to have Java installed on your computer. |
Consistent capitalization of the NeoForge name.
It might also be a good idea to link to the Installing Java article's section laying out which Minecraft version requires which Java version.
|
|
||
| ## Further Help | ||
|
|
||
| This document covers some of the issues you may face as a user of NeoForge, however it is not intended to be exhaustive, and you may run into a problem which is not covered here. |
There was a problem hiding this comment.
| This document covers some of the issues you may face as a user of NeoForge, however it is not intended to be exhaustive, and you may run into a problem which is not covered here. | |
| This documentation covers some of the issues you may face as a user of NeoForge, however it is not intended to be exhaustive, and you may run into a problem which is not covered here. |
As this is not a single document, I believe "documentation" is the better term to use.
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| # Checking for and Installing Java |
There was a problem hiding this comment.
| # Checking for and Installing Java | |
| # Checking For and Installing Java |
| This section provides instructions on how to check your computer for an existing Java installation. | ||
|
|
||
| If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section below. |
There was a problem hiding this comment.
| This section provides instructions on how to check your computer for an existing Java installation. | |
| If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section below. | |
| This section provides instructions on how to check your computer for an existing Java installation. If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section below. |
One paragraph makes this easier to read.
|
|
||
| This can happen for a number of reasons, including out-dated and/or buggy graphics card (GPU) drivers. | ||
|
|
||
| First, check to see whether Minecraft without NeoForge works. If the game launches successfully and does not crash, read on. |
There was a problem hiding this comment.
This should contain more steps. The steps should be:
- Run Minecraft without Neo at all
- Run Neo without any mods
- (Maybe) Binary-searching for broken mods, or asking for support on the Discord
| Due to an interaction between NeoForge's early-loading screen and out-dated/buggy GPU drivers, Minecraft may crash. | ||
|
|
||
| This can sometimes be fixed by updating the drivers for your GPU. |
There was a problem hiding this comment.
| Due to an interaction between NeoForge's early-loading screen and out-dated/buggy GPU drivers, Minecraft may crash. | |
| This can sometimes be fixed by updating the drivers for your GPU. | |
| Due to an interaction between NeoForge's early loading screen and outdated/buggy GPU drivers, Minecraft may crash. This can sometimes be fixed by updating the drivers for your GPU. |
|
|
||
| This can sometimes be fixed by updating the drivers for your GPU. | ||
|
|
||
| Linked below are tools for the three most common GPU manufacturers, which can be used to download and install driver updates. |
There was a problem hiding this comment.
| Linked below are tools for the three most common GPU manufacturers, which can be used to download and install driver updates. | |
| The following list contains links to the three most common GPU manufacturers' websites, which can be used to download and install driver updates: |
| For example, a laptop might have one integrated into the CPU itself as well as a dedicated (discrete) GPU. | ||
| ::: | ||
|
|
||
| If you do not know who manufactured your GPU, how many you have, or even which drivers to update, see the [Further Help] section of the main article for a link to the NeoForged project's Discord server, where you can ask for help. |
There was a problem hiding this comment.
Linking the discord directly here is fine imo, as this is a very specific problem.
| - **NVIDIA**: https://www.nvidia.com/download/index.aspx | ||
|
|
||
| :::note | ||
| It is possible that your computer may have multiple GPUs. |
There was a problem hiding this comment.
Merge with the next paragraph.
Still very much a draft. Some things from the PoC I posted haven't been moved over yet. That's still planned, I'm just waiting on this cold forking off as it's killing my ability to document stuff coherantly. And also making me late on my promises (apologies!).
From the commit log:
Still to be "ported" over and cleaned up from the PoC is the section on installing Java.
The FAQ also has some of the older content commented out with a planned return when brain starts working again properly.
Not all feedback has been acted on yet and one change in particular (on finding a terminal emulator-like app) could already benefit from being moved/refactored.
Preview URL: https://pr-166.neoforged-docs-previews.pages.dev