Contribution Guide for ADViCE Knowledge Base
---
[toc]
# Contributing Content to the ADViCE Knowledge Base
The Knowledge Base consists of two primary parts:
- The [Knowledge Base website](https://alan-turing-institute.github.io/ADViCE/).
- The [Knowledge Base repository](https://github.com/alan-turing-institute/ADViCE/tree/main), where the website contents are stored and managed.

This guide covers how to contribute to the Knowledge Base repository, such that the new contents are displayed on the website.

**Write access to the Knowledge Base will only be granted to ADViCE partners once comprehensive guidance on Knowledge Base operation has been provided. This will minimise risk of accidental changes to the knowledge base, whilst still enabling a relatively fast contribution of content to the Knowledge Base**.
- Digital Catapult: Stephen Haben, Peter Smeed, Vicky Williams
- Energy Systems Catapult: Sam Young, Antonella Collaro
- Alan Turing Institute: Francisco Gómez, Gabin Kayumbi
## Prerequisites
1. You must have a GitHub account.
2. You must have access rights to the Knowledge Base repository. These are disabled by default for safety.
## Structure of ADViCE Knowledge Base repository
Follow this link for the [ADViCE Knowledge Base GitHub repository](https://github.com/alan-turing-institute/ADViCE/tree/main)

Knowledge Base contents are stored in the [content]() folder (see red rectangle below). **Do not modify the content anywhere else please, as this could affect functionality of the website**.

---


---

### Structure of the *content* folder
As described above, all content for the ADViCE Knowledge Base is contained in the *content* folder. ==**Do not modify the content anywhere else please**==

Each section of the Knowledge Base is contained within a folder with its name. Each folder contains the files that belong to that section.
- The KB will only read files in MarkDown format (filename.md). Any other file formats within the folders will be ignored when building the website.
- The ```_index.md``` file inside each folder is the "introduction" file that gives an overview of that section of the KB.
- To add further subsections, you need to create a subfolder and include at least one MarkDown file within that new subfolder, plus an ```_index.md``` file that provides the introduction to the subsection (if needed).
## Procedure
We will always follow the following steps for making a contribution:
1. READ the list of open issues: Ensure that no-one is already working on what you intended to work on
2. .........
There is a specific procedure depending on the content contribution you wish to make:
- Contribute a new text file that is already in MarkDown format
- Contribute a new text file that is not in MarkDown format (e.g. Word, PDF, PPT,...)
- Contribute a video submission (e.g. Webinar video)
- Modify an already existing file in the Knowledge Base
- Create a new section/subsection for the ADViCE Knowledge Base
- Proposing changes to the Knowledge Base
### Contribute a new text file that is already in MarkDown format
- **FIRST CHECK THE LIST OF ISSUES, make sure that no other person is doing what you are intending to work on.**
- Examine and decide where in the knowledge base you would like to add your file. For example, if you want to contribute a new report, you should contribute inside the content/Reports/ folder.
- Create a new issue in the [Knowledge Base GitHub](https://github.com/alan-turing-institute/ADViCE/issues) indicating the contribution that you intend to make. You can use this to post questions, ask for advice, and generally as a discussion thread regarding your contribution.
- ==Create a new branch== where you will be able to upload your file and work on it. This will be where you will work on your file from now on, until you are happy with it.
- 
- Upload your file(s) to the Knowledge Base
- Make sure you are working on the branch you created in the step above
- Create a new subfolder within the folder that you want to contribute your file.
- Upload all your files to the subfolder you just created. **==IMPORTANT: NAME YOUR MARKDOWN FILE EXACTLY *```_index.md```*, otherwise it will not read any images that you have linked==**
- If your file has any images, upload them into that subfolder as well. Don't create further subfolders, as otherwise they won't be found by the file. An example on how to reference images can be found in the [Decarbonisation Challenges report](https://github.com/alan-turing-institute/ADViCE/blob/main/content/Reports/ADViCE%20Challenges%20Report/_index.md)
- Once you have uploaded the file, commit the changes
- 
-
- When prompted, select the option to open a pull request, which will then enable review from other people in the team before pushing to the ADViCE repository.
- **Please make sure that you write an adequate commit message so that we can keep track of changes that have been made to the Knowledge Base in case anything goes wrong and we have to revert changes.**
- Once uploaded to the Main branch, a workflow will be automatically initiated by GitHub to rebuild the Knowledge Base. This typically takes about 15-30 seconds. You can check the rebuild progress by clicking on "Actions"
- 
- Format your file in [MarkDown](https://www.markdownguide.org) according to the [template](https://github.com/alan-turing-institute/ADViCE/blob/main/how-to-contribute/ADViCE-MarkDown-Template.md)
- Make sure you modify the *title* field at the top of the document
- This is important, as this will be the title that will be displayed in the Knowledge Base page and menu
- 
- Ensure the document renders correctly
- Don't worry about the small table that renders at the top. This will not display in the website (this is metadata that will be read by the renderer when displaying the website)
- 

- Contributors with **read** access
- The process is more involved, and you should have a basic knowledge of GitHub/Git and version control.
### Contribute a next file that is not in MarkDown format (e.g. Word, PDF, PPT,...)
If you want to contribute a file that is not in MarkDown format, you will need to additionally provide a description (in MarkDown) of the file that can be included in the website.
- Instructions for users with **write** access
- Examine and decide where in the knowledge base you would like the non-markdown file to be located
- Write a description, in MarkDown, of the file you wish to upload, following the [template](https://github.com/alan-turing-institute/ADViCE/blob/main/how-to-contribute/ADViCE-MarkDown-Template.md), and ensuring it renders correctly (as described in the previous section).
- Upload both the MarkDown description and the original file itself to the desired location of the Knowledge Base.
- Add the URL of the original file to the description file so that users can access and download the file.
- Ensure the new additions render correctly in the Knowledge Base.
### Contribute a video submission (e.g. Webinar video)
- Users with **write** access
- Upload video to YouTube, or any other hosting platform that will generate an accessible link to the video.
- Create a description in MarkDown of the video contents that also includes a link to video on YouTube.
- Upload MarkDown description to desired location in the Knowledge Base.
- Ensure MarkDown file renders appropriately
### Modify an already existing file in the Knowledge Base
- If you have **write** access, you can modify the file directly
- Please make sure that you write an adequate commit message so that we can keep track of changes that have been made to the Knowledge Base in case anything goes wrong and we have to revert changes.
- If you have **read** access, you can create a new issue in the ADViCE GitHub describing the proposed change
- 
- We can discuss in ADViCE meetings
### Create a new section/subsection for the ADViCE Knowledge Base
- Create a new issue in the ADViCE GitHub describing the proposed change
- 
### Proposing changes to the Knowledge Base
- Create a new issue in the ADViCE GitHub describing the proposed change
- 
- Proposed changes can then be discussed in ADViCE meetings
### Best Practices
- If we are talking about external files, or content made by other organisations, it is best to link to their content, rather than uploading the file to our Knowledge Base
# Technical Guidance
- Built with [Hugo](), using the [Hugo Techdoc Theme]()
- Advanced testing guidelines
- Running ADViCE knowledge base locally in your machine
- Make sure you have Hugo and Git/GitHub CLI installed
- Clone the repository
- run ```hugo server -D``` in the command line
- On the browser, type the local URL given in the command line
# Setting up the Knowledge Base
- Install Hugo in your computer
- Follow [these steps](https://gohugo.io/getting-started/quick-start/) (i.e. create local git repository and Hugo site locally first)
- Install Hugo Techdoc
- First cd to folder where you have your project's repository
- Then on the command line run ```
git submodule add https://github.com/thingsym/hugo-theme-techdoc.git themes/hugo-theme-techdoc```
- This way, the files required for the template are installed.
- In the hugo.toml file:
- Change URL to the ADViCE GitHub
- Change ``` theme = 'hugo-theme-techdoc' ```
- Add [Techdoc params](https://thingsym.github.io/hugo-theme-techdoc/getting-started/configuration/) to hugo.toml file
- Remove Algolia stuff and other unnecessary things
- Run ``` git remote add ADViCE-github-url``` to connect to the ADViCE online GitHub repository
- Commit and push all files to remote
- Create a GitHub workflow so that every time content is merged onto the main branch of the ADViCE GitHub, the website is recompiled
- Follow the steps in [this page](https://gohugo.io/hosting-and-deployment/hosting-on-github/), which is literally just creating a YAML GitHub workflow file and marking it as the workflow file in the GitHub repository.
- Going to GitHub Actions, you should be able to see how the workflow is triggered every time you add new content to the ADViCE repository.
- Now we are ready to add files into the *contents* folder