initial commit

.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -1 +1 @@
-# dit-digital-service-manual
+# DIT Digital Service Manual

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/Discovery/discoveryPhaseGuideline.md

@@ -0,0 +1,85 @@
+# A Guideline for Discovery Phase
+
+When you start working on a service in the discovery phase, you can easily get lost if the service has many features. However, the discovery phase is an important and sensitive phase of the development process. Skipping this phase can lead to incomplete services in addition to new bugs and unreported features during the development phase. However, not doing the requirement gathering and documentation in the right ways would lead to the same consequences. You need to take your time researching all the requirements, and do not leave any questions unanswered.
+
+So, how to collect the requirements in the right way? How to cover every corner of the service? Sometimes you need to dig deeper into the services and ask questions that the client can not remember for the time being. 
+
+## How long does the discovery phase take?
+
+It usually takes 2 to 8 weeks, but it can take more than that, depending on the project. However, in the discovery phase you should take your time with researching the service. Because, it is crucial to understand the service very well, and collect the right requirements.
+
+## Where to start your research?
+
+Follow these steps throughout your research. While going through the steps, do not assume any detail of the service and skip steps. 
+
+### 1\. Find the problem
+
+At the very beginning of the research, you must know what is the problem with the current service, then ask for details of the service. Knowing what the problem is will help in understanding the situations your client is going through, and it will lead to a better solution.
+
+### 2\. Define the objectives of this service
+
+Now that you know what is the problem of the current service or the client is going through, you have to define what are the objectives for this project. The objectives later can be used as a metric for how far you have come to solve the problem in the discovery phase. Later on in the development can also be used to see if the service is achieving its purpose.
+
+### 3\. Find the stakeholders
+
+Find out who all the users of this service are? What are their roles? And What is their responsibilities? Finding all the stakeholders is important, but finding the right ones will lead you to a better understanding of the service. Who are the right stakeholders? Users who are heavily involved in the service, the ones that use the service almost all the time and know exactly how it works. These stakeholders need to be interviewed in detail, because they have faced every disadvantage and advantage point of the service.
+
+#### Key points
+
+-   Who uses this service?
+
+-   Find the right stakeholders (The one who uses the service the most)
+
+-   What is their role in the service?
+
+-   What is their responsibility?
+
+-   Build a [mind map](documentationGuideline.md#mind-mapping-guideline) representing all the stakeholders
+
+### 4\. Research the service
+
+After finding all the stakeholders, you need to go through the service with them, and ask questions on any actions you don't understand. Especially researching the right stakeholders, you need to take your time with them, and ask detailed questions. It is important to take those requirements from the stakeholders and turn them into user stories, because they are fresh in your mind, you know why these requirements are needed, and how important they are. Use the template for user story in the [documentation guideline](documentationGuideline.md). After you write all the user stories, build a flowchart representing the workflow of the current service, and try to re-engineer the workflow until you come up with a workflow that meets the objective of this service. When you find a solution for the current service workflow, design a new flowchart according to the [documentation guideline](documentationGuideline.md) for the newly proposed workflow. While re-engineering the current workflow, you have to take the KRG rules and regulations into consideration that will be mentioned in the next step.
+
+#### Key points
+
+-   How does the old service work?
+
+-   How do they want the new service to be?
+
+-   What are the tasks of the users in the current service?
+
+-   What will be the tasks of the users in the proposed service?
+
+-   What is the purpose of each task?
+
+-   Turn the requirements into [user stories](documentationGuideline.md#user-stories-guideline)
+
+-   Build a [flowchart](documentationGuideline.md#flowchart-diagram-guideline) for the workflow of the current and proposed service
+
+### 5\. Find the KRG rules and regulations related to this service
+
+It is important to understand the legislation for building this service, so that you understand why this service exists, and why it is important to be digitized.
+
+#### Key points
+
+-   What are the KRG rules and regulations related to this service?
+
+-   Which of these rules will be removed or amended when changing to the proposed service?
+
+-   Will there be any new KRG rules and regulations added to the proposed service?
+
+-   How do the rules and regulations affect the proposed service?
+
+-   Why do these rules and regulations exist?
+
+### 6\. Share the document with the clients
+
+After you have done your research and documented all the requirements, share all the documentations with them. It is important that you go through the documentation again with the clients, to make sure that you have everything documented and all of them are correct.
+
+#### Key Points
+
+-   Go through the flowchart with the stakeholders
+
+-   Do not make any assumptions in the requirements, make sure the requirements are correct
+
+Now that you have been through all the steps,  you are ready to prepare the final document using this [template](https://docs.google.com/document/d/1FZqdr-2xK0YuyiWsdvuDQHNCscFL4xJHDe9ueMUP_Us/edit) with the help of the [documentation guideline](documentationGuideline.md). It is mandatory for you to use the template for documentation and follow the guideline for ease of understanding the service by the development team.

docs/Discovery/documentationGuideline.md

@@ -0,0 +1,128 @@
+# Documentation Guidelines
+
+## Introduction
+
+Documenting the system requirements is really important in the discovery phase for understanding what the service is, why it exists, and how it can be improved. It will have a lot of impact in the development phase, the development team can understand the system really quickly and build it in less errors. Use this [template](https://docs.google.com/document/u/0/d/1FZqdr-2xK0YuyiWsdvuDQHNCscFL4xJHDe9ueMUP_Us/edit) for documenting the requirements according to the guidelines in this page.
+
+## Mind mapping guideline
+
+
+The mind map diagram is for showing all the stakeholders in hierarchical representation. This diagram is useful for understanding the role and responsibilities of the stakeholders, and getting an overview of how the business structure is.
+
+### How to draw a mind map diagram?
+
+
+-   Write down all the stakeholders in a square shape like this:  
+    ![](../../static/img/documentationGuidelineImgs/mind_map_square.png)
+
+-   All the stakeholders should be connected in a hierarchical way.
+
+-   The square that are in different stages within the diagram should be colored appropriately like the example below:  
+    ![](../../static/img/documentationGuidelineImgs/complete_mind_map.png)
+
+-   In each stage the colors should get lighter as it goes down the hierarchy like the example below:  
+    ![](../../static/img/documentationGuidelineImgs/mind_map_colors.png)
+
+## Functional requirements
+
+Functional requirements define the system's behavior. It can be a business process, a user's need, or a calculation of some data. These requirements later on will be embedded in the system.
+
+### How to write functional requirements? {#How-to-write-functional-requirements}
+
+The functional requirement should be written in the following table format:
+
+|ID|Requirement|Priority|
+|---|-----|-----|
+|#[ID]|[Description of the requirement]|[Use [MoSCoW technique](#moscow-techniques)]|
+|#[ID]|[Description of the requirement]|[Use [MoSCoW technique](#moscow-techniques)]|
+
+Example:  
+
+|ID|Requirement|Priority|
+|---|-----|-----|
+|#1|Citizens must fill out a request form|Must have|
+|#2|Citizens can check the form status|Should have|
+
+## Non-functional requirements
+
+Non-functional requirements define the quality of the system like scalability, responsiveness, serviceability, and reliability.
+
+### How to write non-functional requirements?
+
+The non-functional requirement should be written in the same format as [Functional Requirements](#How-to-write-functional-requirements).
+
+Example:
+
+|ID|Requirement|Priority|
+|---|-----|-----|
+|#1|User should get back results of the search in under 5 seconds|Should have|
+|#2|User should authenticate in a secure method like 2FA|Could have|
+
+## Transition requirements
+
+Any requirements that are needed for replacing the current system with the proposed system should be indicated. The requirements need to be written in a numbered list.
+
+For example:
+
+1.  Two computers are needed for using the system.
+
+2.  All the data in the old system needs to be transferred to the proposed system.
+
+3.  [The rest of the requirements]
+
+## Flowchart diagram guideline
+
+The flowchart diagram is great for understanding the workflow of the system, from where and how it starts until where and how it ends. It is an introduction to how the system works. Therefore, it is necessary for the flowchart to be clear, concise, and cover every aspect of the system.
+
+### How to draw the flowchart diagram?
+
+-   Use [standard UML](https://www.edrawsoft.com/flowchart-symbols.html) shapes for expressing the steps of the workflow.
+
+-   If the workflow starts with a human interaction, the flowchart should start with a stickman shape.  
+    ![](../../static/img/documentationGuidelineImgs/stickman.png)
+
+-   If there are multiple stages for the workflow or different entities involved. The workflow between the stages/entities should be separated by boxes and colors like the example below.  
+    ![](../../static/img/documentationGuidelineImgs/flowchart_example.png)
+
+## User stories guideline
+
+Users are the center of the system, knowing what they need and why they need it will help you build the system in the right way. Therefore, user stories can be helpful in understanding the service that the system provides to its stakeholders.
+
+### How to write the user stories?
+
+It is important for the user stories to be clear and easy to understand, to achieve that follow the format shown below.
+
+|User Story #[ID]|
+|---|-----|
+|Who|[Stakeholder]|
+|What|[Requirement/Task]|
+|Why|[The purpose of this requirement]|
+|Priority|[The priority of the requirement based on [MoSCoW technique](#moscow-techniques)]|
+
+Example:
+
+|User Story #1|
+|---|-----|
+|Who|Citize|
+|What|A citizen needs to attach their national ID to the form.|
+|Why|Because the auditor needs to check the identity of the citizen that filled the form.|
+|Priority|Must have|
+
+-   Every field must be filled out in detail.
+
+-   Each functional requirement needs a user story.
+
+-   [MoSCoW technique](#moscow-techniques) must be used for prioritizing the user stories.
+
+
+## MoSCoW technique guideline {#moscow-techniques}
+
+MoSCoW Techniques are broken down into 4 priorities:
+
+1.  Must have: It means that this requirement must be embedded in the system, and it is the main requirement in the system.
+
+2.  Should have: This requirement should be embedded in the system before shipping it to production, whether it is done early in the process of development or later.
+
+3.  Could have: It means the system can be shipped to production without this requirement, but it is nice to have this functionality in the system.
+
+4.  Will not have: This requirement will not be in the system at all, but it is necessary to point out.

docs/intro.md

@@ -0,0 +1,18 @@
+# Introduction
+
+The Department of Information Technology uses an agile methodology for developing and digitizing government services. The process for developing a digital service is consist of a cycle of three different phases:
+
+## Discovery phase
+
+The first step of the process is to understand what is the service, what are the problems that the service is going through, what the user needs, and what are the constraints related to this service. Understanding all these concepts will help in digitizing or developing the service in the best way possible. The discovery phase is a crucial part of the project life cycle, that is why all the conducted research on the service and the users (citizens or government employees) is documented. This documentation is used later on in the development phase for developing the software the best way possible before shipping it to production. If at the end of the discovery phase you came to a conclusion that the project should not move forward to development, it is okay to stop and save time for other projects that have more priority.
+
+-   [A Guideline for Discovery Phase](./Discovery/discoveryPhaseGuideline.md)
+-   [Documentation Guideline](./Discovery/documentationGuideline.md)
+
+## Development phase
+
+When enough requirements are documented after the discovery phase, the Development team starts developing the system with the latest technologies and standards. Additionally, the DevOps team starts preparing the development environment, and builds the CI/CD pipelines for the project. In this phase the system goes through an iterative development process until the software is ready for production. At the end of each iteration the Business Intelligence and Requirement Analysis team checks if all the requirements are met, then the Quality Assurance team will start testing the software before it is released.
+
+## Production phase
+
+After the software is developed and tested, it is shipped to production. Even in production the software is still monitored for any error or bugs for further improvement. If there are any changes that need to be made, the cycle goes back to the discovery phase where the Business Intelligence and Requirements Analysis team starts researching the changes. Furthermore, handover details of the changes to the Development team, and after changes have been implemented shipping it back to production again.

docusaurus.config.js

@@ -0,0 +1,95 @@
+
+
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'KRG Service Manual',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/krg-logo.png',
+  organizationName: 'Kurdistan Regional Government',
+  projectName: 'dit-digital-service-manual',
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      navbar: {
+        title: 'DIT Digital Service Manual',
+        logo: {
+          alt: 'My Site Logo',
+          src: 'img/krg-logo.png',
+        },
+        items: [
+          {
+            type: 'doc',
+            docId: 'intro',
+            position: 'left',
+            label: 'Docs',
+          },
+          {
+            href: 'https://github.com/AzaKamala/dit-digital-service-manual',
+            label: 'GitHub',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Docs',
+            items: [
+              {
+                label: 'Documentations',
+                to: '/docs/intro',
+              },
+            ],
+          },
+          {
+            title: 'Community',
+            items: [
+              {
+                label: 'Twitter',
+                href: 'https://twitter.com/KRGDIT',
+              },
+            ],
+          },
+          {
+            title: 'More',
+            items: [
+              {
+                label: 'GitHub',
+                href: 'https://github.com/AzaKamala/dit-digital-service-manual',
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear()} DIT Digital Service Manual.`,
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+      },
+    }),
+};
+
+module.exports = config;

package.json

@@ -0,0 +1,37 @@
+{
+  "name": "krg-gds-documentation",
+  "version": "1.0.0",
+  "private": false,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
+  },
+  "dependencies": {
+    "@docusaurus/core": "2.0.0-beta.15",
+    "@docusaurus/preset-classic": "2.0.0-beta.15",
+    "@mdx-js/react": "^1.6.21",
+    "clsx": "^1.1.1",
+    "prism-react-renderer": "^1.2.1",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

sidebars.js

@@ -0,0 +1,6 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+};
+
+module.exports = sidebars;

src/css/custom.css

@@ -0,0 +1,39 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary:#BE9D4B;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+html[data-theme='dark'] {
+  --ifm-color-primary: #BE9D4B;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+}
+
+.docusaurus-highlight-code-line {
+  background-color: rgba(0, 0, 0, 0.1);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+html[data-theme='dark'] .docusaurus-highlight-code-line {
+  background-color: rgba(0, 0, 0, 0.3);
+}

src/pages/index.js

@@ -0,0 +1,6 @@
+import React from 'react';
+import {Redirect} from '@docusaurus/router';
+
+export default function Home() {
+  return <Redirect to="/docs/intro/" />;
+}

src/pages/index.module.css

@@ -0,0 +1,23 @@
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 966px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}