readme and contribution update

Author: lbrick

CONTRIBUTION.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Thanks for contributing to our FlexiHPC User guides repository. Below are ways you can help make the these user guides better.
+
+The easiest way for you to help us is by raising an issue, which will require a GitHub account. For amendments to the documentation, you will need to be familiar with general Git concepts if you'd like to commit substantial changes or even whole new user guides, you will be required to set up the preview environment.
+
+## Raise an issue
+The easiest way to help improve our user guides is by raising an issue in our repository at https://github.com/nesi/flexi-docs.
+
+If you find an issues that needs to be resolved, please have a look through the list of existing issues to see whether your issues hasn't already been reported. If it has, or a closely related issues exists, please add your comments to the existing issue.
+
+If your issue isn't already listed, then create a New Issue. Provide details of your suggestion and include the user guide and url to which your suggestion applies. One of our team members will review your suggestion and resolve it if they can. They may contact you if they need some more clarification.
+
+## Making changes
+
+If you would like to make a minor or substantial contribution, you'll need to ensure you have Git and python installed.
+
+## Checking out the code
+For minor or substantial edits, you will need to clone the repsitory of the documentation source code. This can be done using the Git command:
+```sh
+git clone https://github.com/nesi/flexi-docs.git
+```
+You're now ready to make changes.
+
+### Substantial edits and new user guides
+
+To contribute substantial edits or new user guides, we recommend that you [set up a local development environment](#setting-up-a-local-development-environment), so you can visualise and fine tune your work before you submit it for review.
+You'll need some of your `git` skills with this.
+
+- Clone the repo to your local computer using `git clone`.
+- Step through the setup routine ([below](#setting-up-a-local-development-environment)) to set up your computer for local previews of your edits.
+- Make the edits using your favourite markdown editor.
+- Commit your changes to your branch.
+- Preview your changes using the local preview server that you set up above.
+- When you are happy with your edits or additions, commit your changes to the github repo.
+- Create a PR from your branch into `main` on the github site
+
+Please be prepared to answer questions about your edits and make additional commits.
+
+### Setting up a local development environment
+
+Note for windows users, this process will be much easier if you set up [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install), then the commands below will work within the WSL environment.
+
+### MkDocs Installation
+
+Install mkdocs
+```sh
+python3 -m pip install mkdocs
+```
+
+Install theme and addons
+```sh
+pip install mkdocs-material mkdocs-glightbox mkdocs-literate-nav neoteroi-mkdocs
+```
+
+Once the above items are installed you can then serve the files locally with the below command ensuring you are in the root of the cloned repo
+
+```sh
+mkdocs serve
+```
+
+Then browse to http://localhost:8000/
+
+### Branch the code
+
+To commit your work for review you will need to branch from `main` and into your own branch.
+
+Using the `git` command below and replacing `BRANCH_NAME` with a name that is easy to understand.
+
+```
+git branch BRANCH_NAME
+```
+
+**Example:** `git branch 20230815-USER_NAME-Update_Managing_Images`
+
+With the code branched and MkDocs running you should be free to alter and create.
+
+### Markdown styles and references
+
+All markdown references can be found at the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) reference page.

README.md

@@ -1 +1,34 @@
-# flexi-docs
+# NeSI FlexiHPC User Guide Documentation
+
+This is the content that hosts the site https://nesi.github.io/flexi-docs/
+
+## File layout
+
+### docs/
+
+Location of markdown docs. File structure determines categories and sections. A section or category can be replaced by an index.md file, this will replace the default nav with a page.
+
+### docs/assets
+
+This is broken down into a few things, treat this as site assets like `css`, `images` or `files(pdfs etc)`
+
+
+### docs/base_folder_name
+
+This is normally the base folder structure that houses the markdown documents for that subject, example would be `docs/user-guides` houses all the user guides for flexi
+
+### summary and index
+
+These 2 files are used as the following
+
+`index.md` is the base page for that section or group
+
+`summary.md` is the nav structure for that section or group, if not supplied then the site will tile all markdown docs out
+
+## Theme
+
+https://squidfunk.github.io/mkdocs-material/
+
+## Contributing
+
+We welcome contributions to our FlexiHPC User guides. Please read [CONTRIBUTING.md](CONTRIBUTION.md)