#2253: Fix structure and log documentation

CHANGELOG.adoc

@@ -8,6 +8,7 @@ Release with new features and bugfixes:
 
 * https://github.com/devonfw/IDEasy/issues/1165[#1165]: Fix automatic project import for Eclipse
 * https://github.com/devonfw/IDEasy/issues/2040[#2040]: Fixed buggy workspace selection in the GUI
+* https://github.com/devonfw/IDEasy/issues/2253[#2253]: Fix structure and log documentation
 
 The full list of changes for this release can be found in https://github.com/devonfw/IDEasy/milestone/49?closed=1[milestone 2026.08.002].
 

documentation/log.adoc

@@ -1,6 +1,53 @@
 :toc:
 toc::[]
 
-= log
+= logs
 
-The log directory is used to store log files e.g. for the IDE link:configurator.adoc[configurator]. You may look here for debug information if something goes wrong.
+The log directory is used to store log files created by IDEasy.
+
+Logs are stored in:
+
+----
+$IDE_ROOT/_ide/logs
+----
+
+The log directory can be helpful for troubleshooting and debugging if something goes wrong during execution of IDEasy commands.
+
+Log files are generated for all IDEasy commands except those that only get simple information like `ide help` or `ide version`.
+
+The logs are organized in date-based directories below the `logs` folder.
+
+A typical structure looks similar to:
+
+----
+$IDE_ROOT/_ide/logs
+└── 2026
+    └── 08
+        ├── 04
+        └── 05
+----
+
+The first directory level represents the year, followed by the month and day.
+This structure helps keeping log files organized by date.
+The full path to the log of `ide «command»` will follow this pattern:
+```
+$IDE_ROOT/_ide/logs/«yyyy»/«MM»/«dd»/«project»-ide-«command»-«HH»-«mm»-«ss».log
+```
+
+The only excuse to this pattern are installation and uninstallation logs of IDEasy itself that are stored in the top-level `logs` directory.
+These logs keep the timestamp in their filename (see link:setup.adoc#installation-logs[installation-logs]).
+
+Log files contain detailed diagnostic information such as timestamps, log levels, executed operations, warnings, errors, and stack traces.
+They are intended for troubleshooting and analysing problems during IDEasy execution.
+
+On the console, the visible log level can be influenced with options such as:
+
+----
+ide --debug
+ide --trace
+ide --quiet
+----
+
+However, log files are always written with full trace information to ensure all details required for troubleshooting are available, regardless of the selected console log level.
+
+To remove obsolete data and free disk space, use the `ide cleanup` command.

documentation/structure.adoc

@@ -19,11 +19,11 @@ The directory layout of your `IDEasy` will look like this:
 |  |  ├── IDEasy-doc.pdf
 |  |  └── setup[.bat]
 |  ├──/ link:software.adoc[software]/
-|  ├──/ tmp/
-|  └──/ urls/
+|  ├──/ link:log.adoc[logs]/
+|  ├──/ link:tmp.adoc[tmp]/
+|  └──/ link:urls.adoc[urls]/
 └──/ link:project.adoc[my-project] (link:variables.adoc[$IDE_HOME])
    ├──/ link:conf.adoc[conf]/
-   ├──/ link:log.adoc[log]/
    ├──/ link:settings.adoc[settings]/
    ├──/ link:software.adoc[software]/
    └──/ link:workspaces.adoc[workspaces]/

documentation/tmp.adoc

@@ -0,0 +1,18 @@
+:toc:
+toc::[]
+
+= tmp
+
+The `tmp` directory is located in:
+
+----
+$IDE_ROOT/_ide/tmp
+----
+
+It is used by IDEasy to store temporary files created during command execution.
+Typical examples are temporary extraction folders, intermediate downloads, or files created while installing or updating tools.
+
+Temporary files are not intended to be edited manually.
+If IDEasy is interrupted, for example during a download or extraction, temporary files may remain in this directory.
+
+To free disk space, use the `ide cleanup` command once cleanup support for temporary files is available.

documentation/urls.adoc

@@ -0,0 +1,22 @@
+:toc:
+toc::[]
+
+= urls
+
+The `urls` directory is located in:
+
+----
+$IDE_ROOT/_ide/urls
+----
+
+It contains URL metadata used by IDEasy to resolve download locations for supported tools.
+IDEasy uses this data to find versions, editions, platform-specific archives, and download URLs for tools such as Java, Maven, Node.js, IntelliJ, VS Code, and others.
+
+Technically this is just a clone of the git repository https://github.com/devonfw/ide-urls.git[ide-urls].
+We maintain that repository by nightly workflows that automatically add new tool releases.
+The content of this directory is managed by IDEasy and when accessing the data, IDEasy will automatically update this repository (`git pull`).
+Do not make manual changes to this directory.
+IDEasy will revert your changes automatically and your change gets lost.
+
+In case you really want to test a local change here, you would need to create a local feature branch first and commit your changes before calling `ide` commands.
+However, this is for development and not indented for end-user scenarios.