elastic · AlexanderWert · Mar 7, 2025 · Mar 7, 2025 · Mar 7, 2025
diff --git a/dev-docs/README.md b/dev-docs/README.md
@@ -0,0 +1,96 @@
+# Contributing to the EDOT docs
+
+## Writing the docs
+
+We write the docs in regular markdown.
+
+The site rendering uses the [Just the Docs Jekyll theme](https://just-the-docs.com/).
+
+### Structuring the docs
+
+All docs must be written in the `./docs` directory.
+
+The docs are currently split into three navigation sections:
+
+- default section (no dedicated directory)
+- EDOT Collector (`_edot-collector` dir)
+- EDOT SDKs (`_edot-sdks` dir)
+
+Each markdown file results in a separate page.
+
+Docs pages can be structured hierarchically by using the `parent`, `grand_parent` and `nav_order` properties in the front matter sections in the markdown files:
+
+```
+---
+title: My Page Title
+layout: default
+nav_order: 2
+parent: Use Cases
+---
+```
+
+- `title`: Is the page title shown in the navigation bar. This title is also being used to build hierarchies using the `parent` (and `grand_parent`) properties.
+- `layout`: That property must be set to the value `default` on all markdown files, otherwise the layout might break.
+- `nav_order`: That defines the position of the page in the navigation within it's parent context.
+- `parent`: Put the title of the parent page here to build a hierarchical structure of your docs pages. You can omit that property if the page should at the top level of the corresponding navigation section.
+- `grand_parent`: Use this property to set the grandparent, when the parent title is not unique within a navigation section.
+
+You can find more information in the [Just the Docs theme documentation](https://just-the-docs.com/docs/navigation/main/order/).
+
+### Linking other pages
+
+You can use relative links when linking other pages within the docs. Howewver, please make sure to not use the file suffix `.md` in the links:
+
+**Correct:**
+
+```markdown
+[My Link Text](./relativ/path/to/other_page)
+```
+
+**Incorrect:**
+
+```markdown
+[My Link Text](./relativ/path/to/other_page.md)
+```
+
+### Adding Callouts
+
+In this theme we have defined two types of callouts: `NOTE` and `WARNING`.
+You can use those by putting a `{: .note }` or `{: .warning }` in front of a paragraph:
+
+```markdown
+{: .note }
+My Note paragraph with some text.
+```
+
+For multi-paragraph callouts use the block syntax:
+
+```markdown
+{: .warning }
+> My first warning paragraph.
+>
+> My second warning paragraph.
+```
+
+## Building and previewing the docs site locally
+
+### Prerequisites 
+
+1. Install Ruby. For more information, see [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/) in the Ruby documentation.
+2. Install Bundler. For more information, see [Bundler](https://bundler.io/).
+
+### Preview the docs locally
+
+Initially, install the dependencies:
+
+```bash
+bundle install
+```
+
+Run the site locally:
+
+```bash
+bundle exec jekyll serve
+```
+
+Access your local site under http://localhost:4000/opentelemetry/
diff --git a/docs/_edot-sdks/android/index.md → docs/_edot-sdks/android/android.md b/docs/_edot-sdks/android/index.md → docs/_edot-sdks/android/android.md
diff --git a/docs/_edot-sdks/android/configuration.md b/docs/_edot-sdks/android/configuration.md
@@ -0,0 +1,13 @@
+---
+title: Configuration
+layout: default
+nav_order: 2
+parent: EDOT Android
+---
+
+# Configuring the EDOT Android Agent
+
+TODO: 
+- describe the EDOT Android specific config options
+- describe crucial upstream options
+- refer to / link to the remaining upstream config options
diff --git a/docs/_edot-sdks/android/faq.md b/docs/_edot-sdks/android/faq.md
@@ -0,0 +1,10 @@
+---
+title: Frequently Asked Questions
+layout: default
+nav_order: 6
+parent: EDOT Android
+---
+
+# Frequently Asked Questions on EDOT Android
+
+TODO
diff --git a/docs/_edot-sdks/android/release.md b/docs/_edot-sdks/android/release.md
@@ -0,0 +1,10 @@
+---
+title: Release Notes
+layout: default
+nav_order: 7
+parent: EDOT Android
+---
+
+# Release Notes for the EDOT Android SDK
+
+TODO
diff --git a/docs/_edot-sdks/android/setup/setup.md b/docs/_edot-sdks/android/setup/setup.md
@@ -0,0 +1,13 @@
+---
+title: Setup
+layout: default
+nav_order: 1
+parent: EDOT Android
+---
+
+# Setting up the EDOT Android Agent
+
+TODO:
+- where to download
+- explicit description of basic setup here (even if it overlaps with upstream docs)
+- link to upstream docs for more advanced setup use cases
diff --git a/docs/_edot-sdks/android/supported-technologies.md b/docs/_edot-sdks/android/supported-technologies.md
@@ -0,0 +1,12 @@
+---
+title: Supported Technologies
+layout: default
+nav_order: 3
+parent: EDOT Android
+---
+
+# Technologies Supported by the EDOT Android SDK
+
+TODO:
+- Reference the upstream Java instrumentation.
+- Describe differences (also in default behavior) of EDOT Java compared to upstream.
diff --git a/docs/_edot-sdks/android/troubleshooting.md b/docs/_edot-sdks/android/troubleshooting.md
@@ -0,0 +1,10 @@
+---
+title: Troubleshooting
+layout: default
+nav_order: 4
+parent: EDOT Android
+---
+
+# Troubleshooting the EDOT Android SDK
+
+TODO
diff --git a/docs/_edot-sdks/dotnet/configuration.md b/docs/_edot-sdks/dotnet/configuration.md
@@ -0,0 +1,13 @@
+---
+title: Configuration
+layout: default
+nav_order: 2
+parent: EDOT .NET
+---
+
+# Configuring the EDOT .NET Agent
+
+TODO: 
+- describe the EDOT .NET specific config options
+- describe crucial upstream options
+- refer to / link to the remaining upstream config options
diff --git a/docs/_edot-sdks/dotnet/index.md → docs/_edot-sdks/dotnet/dotnet.md b/docs/_edot-sdks/dotnet/index.md → docs/_edot-sdks/dotnet/dotnet.md
@@ -1,9 +1,9 @@
 ---
 title: EDOT .NET
 layout: default
-nav_order: 3
+nav_order: 5
 ---
 
 ## EDOT .NET
 
-Put some content here
+TODO: Put some content here
diff --git a/docs/_edot-sdks/dotnet/faq.md b/docs/_edot-sdks/dotnet/faq.md
@@ -0,0 +1,10 @@
+---
+title: Frequently Asked Questions
+layout: default
+nav_order: 6
+parent: EDOT .NET
+---
+
+# Frequently Asked Questions on EDOT .NET
+
+TODO
diff --git a/docs/_edot-sdks/dotnet/migration.md b/docs/_edot-sdks/dotnet/migration.md
@@ -0,0 +1,14 @@
+---
+title: Migration
+layout: default
+nav_order: 5
+parent: EDOT .NET
+---
+
+# Migrating to EDOT .NET from Elastic .NET Agent
+
+TODO:
+- migration steps
+- advantages of using EDOT
+- limitations compared to classic agents
+- (optional) performance comparison
diff --git a/docs/_edot-sdks/dotnet/release.md b/docs/_edot-sdks/dotnet/release.md
@@ -0,0 +1,10 @@
+---
+title: Release Notes
+layout: default
+nav_order: 7
+parent: EDOT .NET
+---
+
+# Release Notes for the EDOT .NET Agent
+
+TODO
diff --git a/docs/_edot-sdks/dotnet/setup/setup.md b/docs/_edot-sdks/dotnet/setup/setup.md
@@ -0,0 +1,13 @@
+---
+title: Setup
+layout: default
+nav_order: 1
+parent: EDOT Java
+---
+
+# Setting up the EDOT Java Agent
+
+TODO:
+- where to download
+- explicit description of basic setup here (even if it overlaps with upstream docs)
+- link to upstream docs for more advanced setup use cases
diff --git a/docs/_edot-sdks/dotnet/supported-technologies.md b/docs/_edot-sdks/dotnet/supported-technologies.md
@@ -0,0 +1,12 @@
+---
+title: Supported Technologies
+layout: default
+nav_order: 3
+parent: EDOT .NET
+---
+
+# Technologies Supported by the EDOT .NET Agent
+
+TODO:
+- Reference the upstream .NET instrumentation.
+- Describe differences (also in default behavior) of EDOT .NET compared to upstream.
diff --git a/docs/_edot-sdks/dotnet/troubleshooting.md b/docs/_edot-sdks/dotnet/troubleshooting.md
@@ -0,0 +1,10 @@
+---
+title: Troubleshooting
+layout: default
+nav_order: 4
+parent: EDOT .NET
+---
+
+# Troubleshooting the EDOT .NET Agent
+
+TODO
diff --git a/docs/_edot-sdks/ios/configuration.md b/docs/_edot-sdks/ios/configuration.md
@@ -0,0 +1,13 @@
+---
+title: Configuration
+layout: default
+nav_order: 2
+parent: EDOT iOS
+---
+
+# Configuring the EDOT iOS SDK
+
+TODO: 
+- describe the EDOT iOS specific config options
+- describe crucial upstream options
+- refer to / link to the remaining upstream config options
diff --git a/docs/_edot-sdks/ios/faq.md b/docs/_edot-sdks/ios/faq.md
@@ -0,0 +1,10 @@
+---
+title: Frequently Asked Questions
+layout: default
+nav_order: 6
+parent: EDOT iOS
+---
+
+# Frequently Asked Questions on EDOT iOS
+
+TODO
diff --git a/docs/_edot-sdks/ios/index.md → docs/_edot-sdks/ios/ios.md b/docs/_edot-sdks/ios/index.md → docs/_edot-sdks/ios/ios.md
@@ -1,9 +1,9 @@
 ---
 title: EDOT iOS
 layout: default
-nav_order: 4
+nav_order: 5
 ---
 
 ## EDOT iOS
 
-Put some content here
+TODO: Put some content here
diff --git a/docs/_edot-sdks/ios/release.md b/docs/_edot-sdks/ios/release.md
@@ -0,0 +1,10 @@
+---
+title: Release Notes
+layout: default
+nav_order: 7
+parent: EDOT iOS
+---
+
+# Release Notes for the EDOT iOS SDK
+
+TODO
diff --git a/docs/_edot-sdks/ios/setup/setup.md b/docs/_edot-sdks/ios/setup/setup.md
@@ -0,0 +1,13 @@
+---
+title: Setup
+layout: default
+nav_order: 1
+parent: EDOT iOS
+---
+
+# Setting up the EDOT iOS SDK
+
+TODO:
+- where to download
+- explicit description of basic setup here (even if it overlaps with upstream docs)
+- link to upstream docs for more advanced setup use cases
diff --git a/docs/_edot-sdks/ios/supported-technologies.md b/docs/_edot-sdks/ios/supported-technologies.md
@@ -0,0 +1,12 @@
+---
+title: Supported Technologies
+layout: default
+nav_order: 3
+parent: EDOT iOS
+---
+
+# Technologies Supported by the EDOT iOS SDK
+
+TODO:
+- Reference the upstream iOS instrumentation.
+- Describe differences (also in default behavior) of EDOT iOS compared to upstream.
diff --git a/docs/_edot-sdks/ios/troubleshooting.md b/docs/_edot-sdks/ios/troubleshooting.md
@@ -0,0 +1,10 @@
+---
+title: Troubleshooting
+layout: default
+nav_order: 4
+parent: EDOT iOS
+---
+
+# Troubleshooting the EDOT iOS Agent
+
+TODO
diff --git a/docs/_edot-sdks/java/index.md → docs/_edot-sdks/java/java.md b/docs/_edot-sdks/java/index.md → docs/_edot-sdks/java/java.md
diff --git a/docs/_edot-sdks/java/migration.md b/docs/_edot-sdks/java/migration.md
@@ -5,7 +5,7 @@ nav_order: 5
 parent: EDOT Java
 ---
 
-# Migrating to EDOT Java from Classic Elastic Java Agent
+# Migrating to EDOT Java from the Elastic Java Agent
 
 TODO:
 - migration steps