clarify outputs

README.md

@@ -43,11 +43,9 @@ If you want to change your target InvenioRDM instance, you can set the environme
 
 ### General usage
 
-Run `rocrate_inveniordm <ro-crate-dir>` with `<ro-crate-dir>` being the path to the RO-Crate directory. The record is saved as a draft and not published.
+Run `rocrate_inveniordm <ro-crate-dir>` with `<ro-crate-dir>` being the path to the RO-Crate directory. This will upload the record (including files and metadata) as a draft to your chosen InvenioRDM instance, and save the generated DataCite metadata as `datacite-out.json` in the current directory.
 
-You can publish the record through the web interface of your chosen instance, or you can instead run the same command with the `-p` option to publish the record.
-
-Additional options can be found by running `rocrate_inveniordm --help`:
+By default, the record is not published after upload. You can publish the record through the web interface of your chosen instance, or you can instead run the same command with the `-p` option to re-upload the crate into a new record and publish it immediately.
 
 ### Uploading as a zip file
 
@@ -63,14 +61,18 @@ will result in an uploaded file called `test-ro-crate.zip`.
 
 This tool is a *best-effort* approach. After converting the metadata file, the resulting DataCite file is stored as `datacite-out.json` in the root directory. You can adjust the generated DataCite file as needed, and can run the program in two stages to facilitate this:
 
-First, run the program with the `--no-upload` option, to create the DataCite file without uploading anything to InvenioRDM:
+First, run the program with the `--no-upload` option, to create the DataCite file in the current directory without uploading anything to InvenioRDM:
 
 `rocrate_inveniordm --no-upload <ro-crate-dir>`.
 
 After verifying and adjusting the DataCite file, use the `-d` option to tell the program to use this file for upload and skip the process of conversion:
 
 `rocrate_inveniordm -d <datacite-file> <ro-crate-dir>`.
 
+### Other options
+
+Additional options can be found by running `rocrate_inveniordm --help`.
+
 ## Mapping
 
 The project aims at decoupling the definition of the mapping between RO-Crates and DataCite from code. This means, that users can quickly change/add/remove mapping rules without code changes. 

docs/developer_guide.md

@@ -10,16 +10,21 @@
     - in case of TU Wien test instance: use `https://test.researchdata.tuwien.ac.at/`
 1. Run `source .env` to set the environment variables for the session
 
-If you prefer to set the environment variables `INVENIORDM_API_KEY` and `INVENIORDM_BASE_URL` another way (e.g. in `~/.bashrc`), you can do that instead. However, the `.env` file must also be configured as it is used by `pytest`.
+The `.env` file must always be configured as it is used by `pytest`. However, for the final step, if you prefer to set the environment variables `INVENIORDM_API_KEY` and `INVENIORDM_BASE_URL` another way (e.g. in `~/.bashrc`), you can do that instead. 
 
 ### Set up the Python environment
 
+Clone the repository:
+```
+git clone [email protected]:ResearchObject/ro-crates-deposit.git
+cd ro-crate-inveniordm
+```
+
 If you do not already have `poetry` installed, install it following the [Poetry installation documentation](https://python-poetry.org/docs/#installation).
 
 Then install dependencies from `poetry.lock`:
 
 ```bash
-cd ro-crate-inveniordm
 poetry install
 ```