Unclear documentation

[chbrandt]

Documentation Feedback

General Observations:

• The documentation requires improvements for clarity and comprehensiveness. I’m willing to assist with these enhancements but would appreciate some guidance.

Specific Issues Noted in the Cookbook Page (https://intertwin-eu.github.io/interLink/docs/Cookbook/)

1. Install interLink Section:

   • Subsection: Deploy Remote Components (if any)
     • Issue: The phrase "if any" is vague. What is meant by this?

2. Interlink API Server:

   • Clarity on Terminology:
     • Main Kubernetes Cluster: What distinguishes the "main" cluster? Is there a secondary cluster?
     • SSH Bastion: the meaning of "bastion" is not clear?

3. Start the Tunnel:

   • SSH_TUNNEL_NODE_PORT:
     • Node Clarification: Which node are we referring to? Is it the same as the "main Kubernetes cluster" mentioned earlier?
   • Error Encountered:
     • Following the steps in release 0.3.1-patch2, I encountered the following error:

       $HOME/.interlink/bin/ssh-tunnel -keyfile $HOME/.ssh/id_ecdsa
       2024/11/08 14:29:25 unable to read private key: open : no such file or directory
       

     • Expected Behavior: The final step states: "(...) THIS WILL CORRECTLY FAIL (...)". What does "correctly fail" mean?

4. Plugin Service Section:

   • Create Utility Folders:
     • Environment Assumption: I created the utility folders earlier. Should I be on a different machine when executing this steps?
     • Plugin Clarification: Which "plugin" is being referenced here?
   • Create Configuration File:
     • User Accounts: The instruction states, "you should know by previous steps what to put in place of myusername here." User accounts haven't been discussed in the guide so far. I don't really know where we're runnning now.

Environment

• Operating System: Ubuntu 24.04
• Other related components versions: