Update on SwiftJavaDocumentation (swiftlang#372)

Co-authored-by: Konrad `ktoso` Malawski <[email protected]>

Author: koloyyee

Sources/SwiftJavaDocumentation/Documentation.docc/SupportedFeatures.md

@@ -33,10 +33,10 @@ Java `native` functions. JavaKit simplifies the type conversions
 | Java `abstract class`                  | TODO          |
 | Java `enum`                            | ❌             |
 | Java methods: `static`, member           | ✅ `@JavaMethod` |
-| **This list is very work in progress** |               |
+| **This list is very work in progress** |               |    
 
 
-### JExtract: Java -> Swift
+### JExtract – calling Swift from Java
 
 SwiftJava's `swift-java jextract` tool automates generating Java bindings from Swift sources.
 

Sources/SwiftJavaDocumentation/Documentation.docc/index.md

@@ -11,9 +11,21 @@ Please refer to articles about the specific direction of interoperability you ar
 
 ### Getting started
 
-TODO: Some general intro
+**SwiftJava** provides a set of tools and libraries to enable Java and Swift interoperability. It allows developers to generate bindings to either language from the other, by using either source generation (for Java consuming Swift code) or a combination of Swift macros and source generation (for Swift consuming Java libraries).
 
-If you prefer a video introduction, you may want to this 
+The generated code is highly efficient and less error-prone than manually mapping, and also guarantees memory safety across the boundaries between the languages.
+
+Reasons why you might want to reach for Swift and Java interoperability include, but are not limited to, the following scenarios:
+- Incremental adoption of Swift in an existing Java codebase
+- Reuse existing libraries which exist in one ecosystem, but don't have a direct equivalent in the other
+
+SwiftJava is offering several core libraries which support language interoperability:
+- `JavaKit` (Swift -> Java) - JNI-based support library and Swift macros
+- `SwiftKit` (Java -> Swift) - Support library for Java calling Swift code (either using JNI or FFM)
+- `swift-java` - command line tool; Supports source generation and also dependency management operations
+- Build tool integration - SwiftPM Plugin
+
+If you prefer a video introduction, you may want to watch this 
 [Explore Swift and Java interoperability](https://www.youtube.com/watch?v=QSHO-GUGidA) 
 WWDC 2025 session,
 which is a quick overview of all the features and approaches offered by SwiftJava.
@@ -25,7 +37,7 @@ which is a quick overview of all the features and approaches offered by SwiftJav
 - <doc:SupportedFeatures>
 
 
-### Source generation
+### Source Generation
 
 - <doc:SwiftJavaCommandLineTool>
 - <doc:SwiftPMPlugin>