Merge pull request #6 from digital-land/copy-technical-documentation-…

…repo

Use technical-documentation as a base

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,43 @@
+name: deploy
+
+on:
+  push:
+    branches:
+      - main
+
+# Set permissions of GITHUB_TOKEN
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+    - name: Install dependencies
+      run: npm ci
+    - name: Build with Eleventy
+      run: make build
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,18 @@
+# Built pages
+_site
+
+# Misc
+*.log
+npm-debug.*
+*.scssc
+*.swp
+.DS_Store
+Thumbs.db
+.sass-cache
+.env
+.cache
+
+# Node modules and output
+node_modules
+dist
+src/_includes/css

Makefile

@@ -0,0 +1,29 @@
+SHELL := bash
+.PHONY: init clean
+
+init: 
+	npm install
+
+# old commands for plant uml that could be  useful fin the future
+# .bin:
+# 	@mkdir -p .bin/
+
+# .bin/plantuml.jar: .bin
+# 	@echo "Downloading version $(PLANTUML_VERSION) of plantuml"
+# 	@curl -sL -o .bin/plantuml.jar "https://github.com/plantuml/plantuml/releases/download/v$(PLANTUML_VERSION)/plantuml-$(PLANTUML_VERSION).jar"
+
+# PLANTUML_VERSION := $(shell curl --silent "https://api.github.com/repos/plantuml/plantuml/releases/latest" | jq -rc '.name | .[1:]')
+
+
+clean:
+	@rm -rf .bin/
+
+serve:
+	npx eleventy --serve
+
+build:
+	npx eleventy
+
+
+
+

README.md

@@ -1,2 +1,9 @@
-# service-handbook
+# Planning Data Service Handbook
 A handbook for people working on the Planning Data service.
+
+## Installation
+
+1. Install [Node.js](https://nodejs.org/en/download) v18.17 or later.
+2. Clone or download this repository.
+3. In the `service-handbook` directory, run `make init`.
+4. Run `make serve`.

assets/_settings.scss

@@ -0,0 +1 @@
+$govuk-font-family: Arial, sans-serif;

assets/wiki.css

@@ -0,0 +1,24 @@
+.wiki-nav_item {
+    margin-bottom: 5px;
+    padding-top: 5px;
+}
+
+.wiki-nav_bold {
+    font-weight: bold;
+}
+
+/* .wiki-nav_item::before{
+    color: #505a5f;
+    content: "—";
+    margin-left: -20px
+} */
+
+.wiki-nav_section {
+  list-style: none;
+  margin: 0 0;
+  padding: 0px 0px 0px 20px;
+}
+
+.wiki-nav_section_1 {
+    padding: 0px 0px 0px 0px;
+  }

contributing.md

@@ -0,0 +1,67 @@
+<!-- @stevenjmesser borrowed this from https://github.com/alphagov/design-system-team-docs/ -->
+
+# Contributing to the handbook
+
+Contributions from the team are always welcome! This handbook is currently in alpha, meaning we're testing out what content and guidance is useful. Raising issues and pull requests is strongly encouraged, so that we can develop the handbook as a team.
+
+We continually update this handbook because we're always looking for better ways to get things done. And that changes over time, especially as who works on the team and what we work on changes too.
+
+This document is a guide on contributing to the handbook. It is a live guide and may not be complete, so you can raise problems or queries with a delivery manager, product manager or service owner.
+
+## Who can contribute
+
+Contributions must come from people on the Planning Data team. They are the users of this handbook and the subject matter experts.
+
+## What to contribute
+
+This handbook is for you. It's a reference, a set of docs to turn to when you're unsure about something, so contribute anything that will help you in your day job. 
+
+Step-by-step guides on how to do things and our processes are good. Models, principles, ways of thinking and examples are great. It helps us learn what we do, and how and why we do it.
+
+## How to contribute
+
+How you contribute will depend on your familiarity with working on GitHub, but contributing to the handbook is a safe way to build your skills. 
+
+### 1. Using a text editor
+
+Most people are familiar with text editors like Notepad, Google Docs, Microsoft Word or Notion. You can use whatever is most familiar to you to make a contribution.
+
+Write your contribution and share the document with someone on the team for feedback.
+
+When your document is ready to be published, seek help from a developer or designer to raise a pull request.
+
+### 2. Using the GitHub file editor
+
+You can create and edit files using the GitHub file editor. Most files can be found in their corresponding folder inside the `/docs/` folder. For example, files describing our support processes can be found in `/source/support` folder.
+
+You can follow GitHub's detailed guides on [creating new files](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files) and [editing files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) to create or edit a file. 
+
+<!-- Needs looking at
+### 3. Using a GitHub Codespace
+
+A GitHub Codespace allows you to work on a copy of the handbook on a virtual machine, meaning you don't have to download any files or tools to your machine. It's useful if you've got a locked-down machine. You will use Visual Studio Code and the terminal to create and edit files, and it's easy to get started. 
+
+- In a new tab, visit the [`service-handbook` repository](https://github.com/digital-land/service-handbook) and follow GitHub's guide on [creating a Codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository).
+- Once the Codespace is ready, you will see the Terminal tab is open. It will say something like `@yourgithubusername ➜ /workspaces/service-handbook (branch-name)`. 
+- Type in `gem install middleman` and press Enter. If it's successful, you'll see `Successfully installed middleman`.
+- Type in `bundle install`. If it's successful, you'll see `Bundle complete!`
+- Type in `bundle exec middleman server` and press Enter. If it's successful, you should see a dialog pop up. Click the `Open in browser` button.
+
+A new tab will open which shows a preview of the team docs. You can now create and edit `.html.md.erb` files to add to and edit the docs. Your changes will save automatically but you will need to [commit your changes](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes) to save them for good. 
+
+After you've made all the changes and additions you intended to make, [raise a pull request](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#raising-a-pull-request).
+
+Ask one of our friendly developers for help if you're doing this for the first time. Ask them if they would be happy to help in future too!
+-->
+
+### 3. Using your machine
+
+If you choose this option, you probably know how to do it. Create a branch, commit changes and raise a pull request. Your pull request will be reviewed and approved when ready. You can merge your pull request once approved.
+
+### 4. Create an issue
+
+You can also create an issue to suggest additions and changes without working directly on the files. Add a new issue via the [Issues view](https://github.com/digital-land/service-handbook/issues) to suggest documentation for the handbook.
+
+## Need help?
+
+Ask your team-mates in the team Slack channel, someone will reply and help out.

docs/add-to-the-handbook.md

@@ -0,0 +1,77 @@
+---
+title: Add to the handbook
+---
+<!-- @stevenjmesser borrowed this from https://github.com/alphagov/design-system-team-docs/ -->
+
+## Contributing to the handbook
+
+Contributions from the team are always welcome! This handbook is currently in alpha, meaning we're testing out what content and guidance is useful. Raising issues and pull requests is strongly encouraged, so that we can develop the handbook as a team.
+
+We continually update this handbook because we're always looking for better ways to get things done. And that changes over time, especially as who works on the team and what we work on changes too.
+
+This document is a guide on contributing to the handbook. It is a live guide and may not be complete, so you can raise problems or queries with a delivery manager, product manager or service owner.
+
+### Who can contribute
+
+Contributions must come from people on the Planning Data team. They are the users of this handbook and the subject matter experts.
+
+### What to contribute
+
+{% from "govuk/components/warning-text/macro.njk" import govukWarningText %}
+
+{{ govukWarningText({
+  text: "This handbook is openly available on the public internet. You must not add any information which must remain protected, private or secret.",
+  iconFallbackText: "Warning"
+}) }}
+
+This handbook is for you. It's a reference, a set of docs to turn to when you're unsure about something, so contribute anything that will help you in your day job. 
+
+Step-by-step guides on how to do things and our processes are good. Models, principles, ways of thinking and examples are great. It helps us learn what we do, and how and why we do it.
+
+### How to contribute
+
+How you contribute will depend on your familiarity with working on GitHub, but contributing to the handbook is a safe way to build your skills. 
+
+#### 1. Using a text editor
+
+Most people are familiar with text editors like Notepad, Google Docs, Microsoft Word or Notion. You can use whatever is most familiar to you to make a contribution.
+
+Write your contribution and share the document with someone on the team for feedback.
+
+When your document is ready to be published, seek help from a developer or designer to raise a pull request.
+
+#### 2. Using the GitHub file editor
+
+You can create and edit files using the GitHub file editor. Most files can be found in their corresponding folder inside the `/docs/` folder. For example, files describing our support processes can be found in `/source/support` folder.
+
+You can follow GitHub's detailed guides on [creating new files](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files) and [editing files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) to create or edit a file. 
+
+<!-- Needs looking at
+### 3. Using a GitHub Codespace
+
+A GitHub Codespace allows you to work on a copy of the handbook on a virtual machine, meaning you don't have to download any files or tools to your machine. It's useful if you've got a locked-down machine. You will use Visual Studio Code and the terminal to create and edit files, and it's easy to get started. 
+
+- In a new tab, visit the [`service-handbook` repository](https://github.com/digital-land/service-handbook) and follow GitHub's guide on [creating a Codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository).
+- Once the Codespace is ready, you will see the Terminal tab is open. It will say something like `@yourgithubusername ➜ /workspaces/service-handbook (branch-name)`. 
+- Type in `gem install middleman` and press Enter. If it's successful, you'll see `Successfully installed middleman`.
+- Type in `bundle install`. If it's successful, you'll see `Bundle complete!`
+- Type in `bundle exec middleman server` and press Enter. If it's successful, you should see a dialog pop up. Click the `Open in browser` button.
+
+A new tab will open which shows a preview of the team docs. You can now create and edit `.html.md.erb` files to add to and edit the docs. Your changes will save automatically but you will need to [commit your changes](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes) to save them for good. 
+
+After you've made all the changes and additions you intended to make, [raise a pull request](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#raising-a-pull-request).
+
+Ask one of our friendly developers for help if you're doing this for the first time. Ask them if they would be happy to help in future too!
+-->
+
+#### 3. Using your machine
+
+If you choose this option, you probably know how to do it. Create a branch, commit changes and raise a pull request. Your pull request will be reviewed and approved when ready. You can merge your pull request once approved.
+
+#### 4. Create an issue
+
+You can also create an issue to suggest additions and changes without working directly on the files. Add a new issue via the [Issues view](https://github.com/digital-land/service-handbook/issues) to suggest documentation for the handbook.
+
+### Need help?
+
+Ask your team-mates in the team Slack channel, someone will reply and help out.

docs/index.md

@@ -0,0 +1,20 @@
+---
+homepage: true
+title: About
+---
+{% from "govuk/components/warning-text/macro.njk" import govukWarningText %}
+
+{{ govukWarningText({
+  text: "This is for internal use by the Planning Data team",
+  iconFallbackText: "Warning"
+}) }}
+
+This is a reference guide for who we are and the way we do things. It’s a handbook for anyone in the Planning Data team that tells us the ‘right way’ to do things.
+
+What’s written here is the way we do things now, but that will change from time to time.
+
+## Contribute to the handbook
+
+Contributions from anyone on the team are welcome and encouraged! This handbook is currently in its early stages of development, and we’re still testing out what content and guidance is useful.
+
+Follow the [contribution guide](/add-to-the-handbook/) to add to our handbook.