Merge pull request #4 from pogi7/v1.1.0

version 1.1.0 docs & changelog

changelog/2024-06-24-version-1.1.0/index.md

@@ -0,0 +1,19 @@
+---
+slug: version-1.1.0
+title: 2024-06-24 Version 1.1.0
+authors: [levitt]
+tags: [version-1.1.0]
+---
+
+![Undraw Update](./undraw_Upgrade_re_gano.png)
+
+## All Pages
+- Reformatted content within the pages to answer these 3 questions:
+    1. What is it?
+    2. Why should I care?
+    3. How to implement?
+- Content ties back to 3 main points in main page
+    1. Standarize Development Processes
+    2. Applicable To All Dev Teams
+    3. Lower Rates Of Burnout
+

versioned_docs/version-v1.1.0/advanced-tips/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Advanced Tips",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Advanced Tips for Pleasant and Effective Digital Transformation."
+  }
+}

versioned_docs/version-v1.1.0/advanced-tips/agile-development.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+---
+
+# Agile Development
+
+Adopting an agile way of thinking within a dev team is an important way to improve the pleasantness and effectiveness of a team's DX.
+
+Agile development is a way of thinking.  It's a culture that a team should adopt.  Agile is usually used in processes that can improved iteratively and where order of operations isn't extremely important.  Agile is usually not used to its fullest in industries that need to be risk adverse such as healthcare or space exploration.
+
+## DevSecOps
+
+### What is it? 
+[DevSecOps](https://www.redhat.com/en/topics/devops/what-is-devsecops) or Development, Security, and Operations is a way of implementing agile by having the dev team be responsible for the development, security, and operations of the app instead of passing those responsibilities off to other dev teams. 
+
+### Why should I care? 
+[DevSecOps](https://www.eccouncil.org/cybersecurity-exchange/devsecops/it-industries-adopt-devsecops/) leads to faster delivery times during the software development lifecycle without deprioritizing security, repeatable and standarized software processes, and save costs by reducing errors and refactoring through automating repetitive tasks. 
+
+### How to Implement? 
+1. [CICD](https://www.redhat.com/en/topics/devops/what-is-ci-cd): Continuous Integration and Continuous Deployment is way to achieve DevSecOps by having the dev team continuously integrate new changes to the app and continuously deploying these changes to the app.  This is commonly used to automatically build and test an app to ensure that the app functions as intended and verify that there is high code quality.
+
+## Scrum
+
+### What is it? 
+[Scrum](https://www.atlassian.com/agile/scrum) is one way that Agile can be achieved where there is a fixed increment of when to do work (i.e 2 weeks, 1 month, etc.).  There are required roles such as scrum master or product owner in order to implement scrum.
+
+### Why should I care? 
+Scrum standardizes development processses since it is designed to deliver value in fixed increments.
+
+### How to Implement? 
+1. Scrum boards and ticket system: According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-asynchronous-tools), the most widely used ticket system by personal and professional developers for scrum is [Jira](https://www.atlassian.com/software/jira)
+
+## Kanban
+
+### What is it? 
+[Kanban](https://www.atlassian.com/agile/kanban) is another way that Agile can be achieved where there is no fixed increment of when to do work (i.e 2 weeks, 1 month, etc.).  There are no required roles such as scrum master or product owner in order to implement Kanban but a board is required for Kanban to be fully achieved.
+
+### Why should I care? 
+Kanban is less rigid than scrum allowing the development team to adapt to changes faster.  This can help prevent developer burnout as the development team can be more flexible to changing needs.
+
+### How to Implement? 
+1. Kanban boards and ticket system: According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-asynchronous-tools), the most widely used ticket system by personal and professional developers for kanban is [Jira](https://www.atlassian.com/software/jira)

versioned_docs/version-v1.1.0/advanced-tips/artificial-intelligence.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 2
+---
+
+# Artifical Intelligence
+
+Artifical intelligence is a great tool that can vastly improve the pleasantness and effectiveness of a developer's experience.
+
+## LLM 
+
+### What is it? 
+LLM or Large Language Models are great tools since they have been trained on large data sets.  This means that LLMs can usually generate an answer if you give it a sufficient prompt.  LLM are very popular since they can give an answer very quickly.  Sometimes LLM will hallucinate which by giving an incorrect answer while claiming it's correct.  It's a good idea to always verify the output a LLM gives.
+
+### Why should I care? 
+It is important to verify the output that LLMs give, but they are able to generate a text or code and retrieve information.  Since LLMs are trained on very large data sets this ability to generate code or text and retrieve information is applicable to all development teams.  According to [Stack Overflow's 2023 insights](https://survey.stackoverflow.co/2023/#section-sentiment-and-usage-ai-tools-in-the-development-process), use of AI specifically LLMs are on the rise for personal and professional developers.
+
+### How to Implement? 
+1. [ChatGPT](https://chat.openai.com) is the most popular and can be accessed through their API or web interface
+2. [ClaudeAI](https://claude.ai) can be accessed through their web interface
+3. [PerplexityAI](https://www.perplexity.ai/) can be accessed through their web interface.  Generated text or code is sited.
+4. [Github Copilot](https://github.com/features/copilot) can be accessed through their IDE extension.
+5. [Tabnine](https://www.tabnine.com) can be accessed through their IDE extension.
+
+## Rules Based AI
+
+### What is it? 
+Rules Based AI is slightly less known than LLM that are trained using machine learning.  Rules based AI generates responses based on a set of known and predefined rules.  This means that rules based AI will always give a correct answer based on its predefined rules, but it is [slower](https://medium.com/@byanalytixlabs/generative-ai-vs-traditional-ai-understand-key-differences-ca2d3e37c45d) than a LLM.
+
+### Why should I care? 
+Industries that can't afford hallucinations like healthcare or space exploration should use rules based AI on production quality software.  This will lead to higher code quality and prevent bugs from appearing in the production code.
+
+### How to Implement? 
+1. [RDFox](https://www.oxfordsemantic.tech/rdfox) is a graph database that has a rules based AI that "reasons" about data.

versioned_docs/version-v1.1.0/advanced-tips/package-manager.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 3
+---
+
+# Package Managers
+
+Package managers are an important way to improve the pleasantness and effectiveness of DX.
+
+### What is it? 
+Package managers add, remove, modify, upgrade, and maintain software.  There are package managers at the OS, programming language, or app level.
+
+### Why should I care? 
+Package managers standarize how 3rd party dependencies and software can be maintained throughout the lifecycle of an app.  This standardization leads to quicker onboarding, higher success of knowledge transfer, and less user-error bugs.
+
+### How to Implement? 
+1. [Chocolatey](https://chocolatey.org/) Windows Package Manager
+2. [HomeBrew](https://brew.sh/) macOS Package Manager
+3. [APT](https://en.wikipedia.org/wiki/APT_(software)) Linux Debian Package Manager
+4. [pyPI](https://pypi.org/) Python Package Manager
+5. [npm](https://www.npmjs.com/) Javascript Package Manager
+6. [Helm](https://helm.sh) Kubernetes Package Manager

versioned_docs/version-v1.1.0/advanced-tips/standard-development-environment.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 4
+---
+
+# Standard Development Environments
+
+Package managers are a good way to standardize the way that software is developed in a dev team leading to an improvement in the pleasantness and effectiveness of DX.
+
+### What is it? 
+A standard development environment is where all developers in the dev team have the same environment in which they do development.  This is usually at the OS, programming language, and app level.
+
+### Why should I care? 
+Standard development environments help developers work on the same platform.  Typically development teams also develop using the same platform (not the same hosting environment) as the production environment. Like package managers, this standardization leads to quicker onboarding, higher success of knowledge transfer, and less user-error bugs introduced into the code base.  A common complaint people will say when standard development environments are not implemented is `It works on my machine!`.  Standard development environments mitigates the occurence of this problem from occuring as often.
+
+### How to Implement? 
+1. Common development server: While expensive this ensures all developers are using the same development environment
+2. Docker: While having a learning curve, it does not alter the host OS so when docker is stopped a developer can go back to using Windows, macOS, or Linux.  According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-other-tools), widely used by personal and professional developers.
+3. Track software dependencies in a file: For programming languages or apps, that is usually a [requirements.txt](https://learnpython.com/blog/python-requirements-file/)(Python), [package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)(Javascript), or [values.yml](https://helm.sh/docs/chart_template_guide/values_files/#helm)(Kubernetes's Helm) file.

versioned_docs/version-v1.1.0/advanced-tips/user-experience.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 5
+---
+
+# User Experience
+
+Spending some time to think about the user experience of the app will help improve DX pleasantness and effectiveness.
+
+User experience is something for the design team to be thinking about but having a general knowledge of it will be important to improve DX.
+
+### What is it? 
+For digital transformation, [user experience](https://www.nngroup.com/articles/definition-user-experience/) includes all end user's interactions with a service, app, or piece of software. 
+
+### Why should I care? 
+A [good user experience](https://www.uxdesigninstitute.com/blog/the-value-of-ux-design/) is generally easy and enjoyable, while a bad user experience is complicated, confusing and frustrating.  Bad user experience may lead to an increase in code refactors.  This may lead to burn out of the development team.
+
+### How to Implement? 
+1. Get a Designer: Dev teams will sometime have people wear multiple hats while doing development.  One of these hats is designer.  It is highly recommended to get a designer who is trained and knows what they're doing instead of wearing multiple hats.
+2. Listen to Your Designer: It's always a good idea to listen to your designer.  A lot of research goes into making a good user experience.  Information is usually conveyed in a Figma diagram, survey information, or PowerPoint presentation.
+3. [Figma](https://www.figma.com) is an app commonly used by designers to make designs for the web, mobile, watches, etc. and share those with others.  For a dev team, this design is usually what inspires the look and feel of the frontend.
+
+While accessibility is a different concept than user experience, the two topics are related.  Figma can also be used to verify that your app meets accessibility requirements like the ones outlined in [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/).  Some accessibility concerns can be ensuring that the app's colors comply to requirements for people with color blindness.

versioned_docs/version-v1.1.0/intro.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 1
+---
+
+# Basic Tips
+
+Let's discover the basics of pleasant and effective **digital transformation in less than 5 minutes**.
+
+## Version Control
+
+### What is it? 
+[Version control](https://www.atlassian.com/git/tutorials/what-is-version-control) is a way to keep track and manage changes to software code.  
+
+### Why should I care? 
+Version control can allow developer teams to keep track, mitigate, and resolve errors that may arise from code degradation or human error which leads to a more pleasant and effective digital transformation.
+
+### How to Implement? 
+1. Git: According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#version-control-version-control-system), Git is the de facto version control software that personal and professional developers use.
+2. Github: According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-version-control-version-control-platforms), Github is the most used version control platform that personal and professional developers use.
+
+<!-- @Deprecated for v2.0.0 ### Git
+
+:::tip What is Git?
+
+[Atlassian](https://www.atlassian.com/git/tutorials/what-is-git) does a good job explaining what Git is and the benefits of adopting the technology within a development team.
+
+:::
+
+According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#version-control-version-control-system), Git is the de facto version control software that personal and professional developers use.
+
+Git is used for managing code locally on a computer.  This computer can be a personal computer, a bare metal server, or a cloud instance.
+
+Git stores code in repos.  These local repos can be stored on remote hosting services.
+
+### Github
+
+:::tip What is Github?
+
+[Github](https://docs.github.com/en/get-started/start-your-journey/about-github-and-git) does a good job explaining how Git and Github interact with each other and the benefits of using Github.
+
+:::
+
+According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-version-control-version-control-platforms), Github is the most used version control platform that personal and professional developers use.
+
+Github is used to store Git repos that can be accessed by developers with the correct authorization.  
+
+For a developer, Github is used for a development team to see new changes in a codebase and keep track of and manage those changes.
+
+An example of a Github repo is shown [here](https://github.com/opencaesar/oml-vision) -->
+
+## Documenting Code
+
+### What is it? 
+Documenting code is very important because it allows you and the rest of the development team to understand how your code works and is supposed to behave.
+
+### Why should I care? 
+Documentation helps dev teams onboard new developers much faster and prevent information from being lost due to turnover or forgetting.  This is applicable to all dev teams.
+
+### How to Implement? 
+1. Code Comments: Code comments are very helpful for developers because you can put the code documentation right next to the code.  It is highly recommended to follow the documentation standard for your language that your dev team is using.  If your language doesn't have a standard then it's important to be consistent with how you write your documentation.
+2. READMEs: READMEs are nice to explain higher level functionality of a program, function, class, or piece of software within an app or a piece of software that interacts with your dev team's app.  READMEs can be included at any level of a Git repo, but generally recommended at the root or top level of a repo so that all developers will know where the README is.
+3. Wikis: Wikis are a good alternative to READMEs when you don't want to store high level documentation about your app inside a Git repo.  According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-asynchronous-tools), a very common wiki that dev teams use is [Confluence](https://www.atlassian.com/software/confluence)
+
+<!-- @Deprecated for v2.0.0 ### Comments
+
+Code comments are very helpful for developers because you can put the code documentation right next to the code.  
+
+It is highly recommended to follow the documentation standard for your language that your dev team is using.
+
+The list includes some of the most widely used programming languages from [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-programming-scripting-and-markup-languages):
+- [Python](https://peps.python.org/pep-0257/)
+- [Java](https://www.baeldung.com/javadoc#javadoc-comments)
+- [Typescript](https://tsdoc.org/)
+
+An example of a Typescript comment that matches a Typescript standard is shown [here](https://github.com/opencaesar/oml-vision/blob/0db2cc46778f1441474c0d4aebc071df453cf52d/controller/src/utilities/loaders/loadCommandFiles.ts#L6-L15)
+
+### READMEs
+
+READMEs are nice to explain higher level functionality of a program, function, class, or piece of software within an app or a piece of software that interacts with your dev team's app.
+
+READMEs can be included at any level of a Git repo, but generally recommended at the root or top level of a repo so that all developers will know where the README is.  
+
+READMEs can be written in any programming language, but they are generally written in [plain text](https://www.adobe.com/uk/acrobat/resources/document-files/text-files/txt.html) (.txt) or [Markdown](https://www.markdownguide.org/) (.md) files.
+
+An example of a README.md in a Github repo is shown [here](https://github.com/opencaesar/oml-vision/blob/0db2cc46778f1441474c0d4aebc071df453cf52d/README.md)
+
+### Wikis
+
+Wikis are a good alternative to READMEs when you don't want to store high level documentation about your app inside a Git repo.
+
+According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-asynchronous-tools), a very common wiki that dev teams use is [Confluence](https://www.atlassian.com/software/confluence)  
+
+An example of a Confluence page detailing the architecture of an app is shown [here](https://openmbee.atlassian.net/wiki/spaces/OPENMBEE/pages/320765953/Flexo-MMS+Architecture) -->

versioned_sidebars/version-v1.1.0-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "tutorialSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

versions.json

@@ -1,3 +1,4 @@
 [
+  "v1.1.0",
   "v1.0.0"
 ]