Getting Started with ICS Documentation

This guide walks you through the process of connecting to a Git repository with your preferred markdown editor and submitting your documentation changes. It assumes you have basic knowledge of version control and markdown editing.

Prerequisites

• Basic understanding of Git and version control.
• A preferred markdown editor installed (e.g., VSCode, Obsidian). Configuration details for each editor can be found in their specific cookbooks.

1. Choose and Configure Your Markdown Editor

Before you start working with Git repositories, ensure your preferred markdown editor is configured correctly. This guide uses VSCode and Obsidian as examples, but the process should be similar for other editors.

• VSCode: Install the GitLens extension to enhance your Git experience. Access the Extensions view by clicking on the square icon on the sidebar or pressing Ctrl+Shift+X, then search for GitLens to install.
• Obsidian: Make sure you've enabled the Git plugin. Go to Settings > Community plugins, click on Browse, search for the Git plugin, and install it.

2. Clone the Repository

To work on the documentation, first clone the repository to your local workspace:

1. Open your terminal or command prompt.
2. Navigate to the folder where you want to clone the repository.
3. Run the command: git clone [repository URL]. You'll find the repository URL on the project's Git hosting service page.

3. Create a New Branch

Creating a new branch for your changes is crucial for maintaining workflow integrity:

1. In your terminal, navigate to the cloned repository directory.
2. Create a new branch with the command: git checkout -b your-branch-name.

Replace your-branch-name with a meaningful name for your work (e.g., update-installation-docs).

4. Update Documentation Using Your Editor

Open the cloned repository in your markdown editor and make the necessary documentation updates. Remember, the focus is on the content that achieves the goal, not on explaining concepts.

5. Commit and Push Your Changes

After making your changes:

1. Open your terminal within the repository directory.
2. Stage your changes with git add . to add all files or git add [file name] for specific files.
3. Commit your changes with git commit -m "A meaningful commit message".
4. Push the changes to the remote repository with git push origin your-branch-name.

6. Submit a Pull Request

Go to the Git hosting service web page for your repository and initiate a pull request from your branch to the main branch. Fill in the details of your changes and submit the request for review.

Conclusion

Once your pull request is approved and merged into the main branch, your changes will be part of the documentation and published to the corresponding websites. This guide ensures your contributions are effectively integrated into the project's documentation workflow.