Where the Docs Actually Are
The JBoss Enterprise Application Platform 7 documentation lives on Red Hat's customer portal at access.redhat.com/documentation. If you're using the community WildFly distribution, those docs moved to wildfly.org, but most people asking about JBoss AS 7 are dealing with the EAP branch and its support contracts. The documentation is split into separate manuals by component: installation guides, administration and configuration, security guides, deployment guides, and migration documents for moving from older versions. I spent a week last year trying to get a JMX remoting endpoint to authenticate properly against an LDAP backend on EAP 7.1. The docs say you configure the remoting connector and bind it to a security domain. That's technically correct and completely unhelpful. The actual problem was that the JAAS configuration needed a specific module dependency that isn't listed in the security chapter. I found the workaround by searching through the module XML files in the server's modules directory and tracing which ones provided the javax.security.auth.spi classes. The connector refused to start with any LDAP provider unless I added org.picketbox as a dependency in my custom module. The documentation doesn't mention this dependency requirement anywhere in the security section. Here's how I actually used the docs in that situation. I started with the Administration and Configuration Guide for EAP 7, pulled up the section on management interfaces. It described the remoting connector configuration with XML snippets. I applied the snippets to standalone-full-ha.xml and the server wouldn't boot. The error logs pointed to missing classes but didn't name the module. I cross-referenced with the Modular Structure guide, which at least lists what's available in the module system. From there I traced the classpath and found the right dependency. It took two days instead of twenty minutes.
The documentation quality varies significantly between sections. The installation guide is generally solid and accurate. The migration guide from JBoss AS 6 to EAP 7 has real gaps. I encountered a case where the datasources subsystem XML schema changed between AS 6.4 and EAP 7, and the migration documentation showed the old format. Applications that looked correct after following the guide failed at runtime with classloader errors because the JDBC driver module structure was completely different in EAP 7. The workaround was to manually rebuild the driver module directory under modules/system/layers/base/com/mysql/main and create a proper module.xml with the correct resource-root configuration. The migration doc assumes you're doing a clean install and never covers existing driver configurations.
What the Docs Get Wrong or Leave Out
One thing nobody in the documentation warns you about is the CLI syntax difference between version 7.1 and 7.2. In 7.1, you could reference subsystems by their display name. In 7.2, Red Hat changed the addressing model and some of those shortcuts stopped working. If you have automation scripts built against the 7.1 CLI syntax, they break on 7.2. The upgrade guide mentions this in a single paragraph near the end. I had a deployment pipeline that failed because a handful of CLI commands in a Jenkins job used the old addressing syntax. The fix was to rewrite the affected commands to use the new fully qualified addresses. It took about three hours to identify which commands were broken by comparing the CLI help output between the two versions. Another gap is in the clustering documentation. The guide explains how to configure JGroups channels and the web clustering subsystem. It does not explain what happens when you have a mixed version cluster where one node is running 7.0 and another is running 7.2. I found out through trial and error that the binary protocol changed between those versions and nodes couldn't form a cluster. You have to upgrade all nodes to at least 7.1 before mixing further. The documentation treats clustering as if everyone is on the same patch level, which is a common pattern. Real production environments rarely match that assumption.
Get the Full Details
How I Actually Navigate the Documentation
Rather than reading the docs linearly, which takes too long and misses context, I search by error message first. The Red Hat Knowledgebase at access.redhat.com solves more problems than the official documentation does. A lot of the edge cases I've hit have solution articles there that reference the relevant doc sections. I use the knowledgebase for troubleshooting and the documentation for understanding the baseline configuration model. For configuration reference, the Management CLI guide is more useful than the Administration and Configuration Guide. The CLI guide shows you the exact command syntax and what each parameter does. The configuration guide describes concepts in prose, which is slower to parse when you're trying to fix something at 2 AM. I keep the CLI guide bookmarked and refer to it almost exclusively for operational work. The downloadable PDF versions of the documentation are sometimes more up to date than the online versions because the online docs get updated continuously and the PDFs represent a fixed release. If you're working offline or need a stable reference, download the PDFs for your specific EAP version. They're available from the same Red Hat documentation page. The PDFs are around 400 to 800 pages each depending on which manual you pull.
When the Docs Are Not Enough
There are scenarios where the documentation simply won't help. Custom security domains with non-standard LDAP schemas are one. The security guide covers Active Directory and generic LDAP, but if your organization uses a custom schema with non-standard attribute mappings, you're on your own. I've had to look at the PicketBox source code directly to understand how the LDAP login module processes group membership. The documentation describes the configuration properties but not the lookup logic. Performance tuning is another area where the docs are inadequate. The performance guide gives baseline recommendations like heap size and thread pool counts. It doesn't cover what to do when your application has a specific bottleneck like connection pool saturation under burst traffic. I've spent time profiling these situations with VisualVM and JConsole and comparing the results against the documented defaults. The defaults are conservative and usually need adjustment for production workloads. There's no documented methodology for determining the right values for your specific application. Transaction timeout behavior across distributed transactions involving multiple datasources is poorly documented. The guide states that the default transaction timeout is 300 seconds and you can change it with the default-timeout attribute. It does not explain what happens when one resource manager in the transaction takes longer than another and how the JTA coordinator handles the timeout propagation. I learned this the hard way when a long-running batch job was being rolled back mid-commit and the logs didn't make it obvious why. The issue was that the underlying resource adapter had a shorter internal timeout than the JTA transaction timeout, and the adapter aborted the branch before the coordinator could finish. The fix involved aligning the resource adapter configuration with the JTA settings. Nothing in the documentation connects these two configuration areas.
