reformat documentation to better tie into the main point on the home …

…page

Signed-off-by: pogi7 <[email protected]>

README.md

@@ -1,4 +1,4 @@
-# Developer Experience Tips
+# Digital Transformation Tips
 
 ## Source Code
 Link to [Source Code](https://github.com/pogi7/dx-tips)

docs/advanced-tips/_category_.json

@@ -3,6 +3,6 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "Advanced Tips for Pleasant and Effective Developer Experience."
+    "description": "Advanced Tips for Pleasant and Effective Digital Transformation."
   }
 }

docs/advanced-tips/agile-development.md

@@ -10,46 +10,33 @@ Agile development is a way of thinking.  It's a culture that a team should adopt
 
 ## DevSecOps
 
-[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.
+### 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. 
 
-### CICD Pipelines
-
-[CICD](https://www.redhat.com/en/topics/devops/what-is-ci-cd) or 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.
-
-An example of a CICD pipeline using Github Actions can be found [here](https://github.com/pogi7/dx-tips/actions)
-
-:::tip This app is deployed using a CICD pipeline
-
-:::
+### 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
-[Scrum](https://www.atlassian.com/agile/scrum) is one way that Agile can be achieved.
 
-Pros: 
-- Fixed increment of when to do work (i.e 2 weeks, 1 month, etc.)
-- Incremental improvements to the app
+### 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.
 
-Cons:
-- Meeting heavy
-- Required roles such as scrum master, product owner, etc.
+### 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
 
-[Kanban](https://www.atlassian.com/agile/kanban) is another way that Agile can be achieved.
-
-Pros: 
-- Meeting Light
-- Continuous improvements to the app
-
-Cons:
-- No fixed increment of when to do work (i.e 2 weeks, 1 month, etc.)
-- Work continuously comes in with little room for planning this work when compared to scrum
+### 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.
 
-## Ticket System
-Both Scrum and Kanban use a ticket system to keep track of work.  These tickets help developers organize the requirements for their work and determining when their work is finished for a particular feature request or bug report.
+### 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.
 
-- 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 is [Jira](https://www.atlassian.com/software/jira)
+### 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)

docs/advanced-tips/artificial-intelligence.md

@@ -8,51 +8,26 @@ Artifical intelligence is a great tool that can vastly improve the pleasantness
 
 ## LLM 
 
-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.
+### 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.
 
-LLM or Large Language Models are great tools since they have been trained on large data sets.  
+### 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.
 
-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.
-
-:::tip Prompt Engineering
-
-[AWS](https://aws.amazon.com/what-is/prompt-engineering/) does a good job explaining what prompt engineering is and the benefits of good prompt engineering when trying to get answers from a LLM.
-
-:::
-
-### API
-
-LLMs can be accessed through their API.  This allows developer flexibility in how the LLM can generate information for an app.
-
-OpenAI's example of their LLM API is found [here](https://platform.openai.com/)
-
-### Web Interface
-
-Most people are most familiar with the web interface on interacting with LLMs.  [ChatGPT](https://chat.openai.com) is the most popular, but their are others such as Anthropic's [ClaudeAI](https://claude.ai).
-
-Personal and professional developers will use the web interface to input a prompt and ask the AI to either generate or interpret code and documentation.
-
-### IDE Extensions
-
-IDE (Integrated Development Environment) Extensions help developers incorporate a LLM into the platform they use to write code and documentation.
-
-Some examples of AI LLM IDE Extensions include
-- [Github Copilot](https://github.com/features/copilot)
-- [Tabnine](https://www.tabnine.com)
+### 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
 
-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 significantly slower than a LLM.
-
-Industries that can't afford hallucinations like healthcare or space exploration are more likely to use rules based AI on production quality software.
-
+### 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.
 
-### Database
+### 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.
 
-One way to get around the slower nature of a rules based AI is to incorporate the rules into a database.  One database that does is called [RDFox](https://www.oxfordsemantic.tech/rdfox).  The rules based AI is incoporated when the database "reasons" about data.
+### How to Implement? 
+1. [RDFox](https://www.oxfordsemantic.tech/rdfox) is a graph database that has a rules based AI that "reasons" about data.

docs/advanced-tips/package-manager.md

@@ -6,48 +6,16 @@ sidebar_position: 3
 
 Package managers are an important way to improve the pleasantness and effectiveness of DX.
 
-All package managers are used to add, remove, modify, upgrade, and maintain software.
-
-## OS Level
-
-For most developers an OS (operating system) level package manager will be the most important package manager to use.  These package managers install software into a common folder on a computer making managing software much easier.
-
-### Windows
-
-By default, Windows does not come with a package manager.  
-
-The two most common Windows package managers are:
-- [Chocolatey](https://chocolatey.org/)
-- [Scoop](https://scoop.sh/)
-
-### macOS
-
-By default, macOS does not come with a package manager.  
-
-The most common macOS package manager is:
-- [HomeBrew](https://brew.sh/)
-
-According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-other-tools), homebrew is the most widely used OS level package manager.
-
-### Linux
-
-By default, Linux comes with a package manager.
-
-Each distro of Linux comes with a unique package manager but here are the most common:
-- [DNF](https://en.wikipedia.org/wiki/DNF_(software))
-- [APT](https://en.wikipedia.org/wiki/APT_(software))
-
-## Programming Language Level
-
-Most programming languages have package managers.  These package managers are used to get libraries or dependencies from open source repositories that have been published to the registry of the package managers.
-
-Most programming languages have a package manager but here are some for the most popular programming languages:
-- [pyPI](https://pypi.org/)
-- [npm](https://www.npmjs.com/)
-- [maven](https://maven.apache.org/)
-
-## App Level
-
-Some large scale apps have package managers as well.  This helps since a developer does not need to recreate functionality if it already on the app's package manager registry.
-
-An example of an app having a package manager is Kubernetes's [Helm](https://helm.sh)
+### 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

docs/advanced-tips/standard-development-environment.md

@@ -6,60 +6,13 @@ sidebar_position: 4
 
 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.
 
-## OS 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.
 
-For most developers standardizing the development environment at the OS (operating system) level is the most important improvement to DX.  
-
-A common complaint people will say is `It works on my machine!` when this isn't done right.
-
-### Force Everyone to Have the Same Local OS
-
-Pros: 
-- All developers are on the same local OS.
-
-Cons:
-- People may be comfortable with Windows, macOS, or Linux to do other things that doesn't involve development.
-- Local OS may get out of date
-
-### Developers working On a Common Server
-
-Pros: 
-- All developers are on the same common OS.
-- All software can be installed on the server.
-- Can be hosted in the cloud or on-premises (on-prem)
-
-Cons:
-- Expensive 
-- Performance will suffer as more devs come into the project and the app becomes more resource intensive
-
-### Docker
-
-Pros: 
-- 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.
-- Docker can be run on any machine (cloud, local, server, etc.) that has the Docker engine installed
-- New OS is run in the docker container which can be used to standardize development environments for the dev team
-- Can be easily integrated into an IDE.  For example VSCode has [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) which use Docker
-
-Cons:
-- Moderately to High Learning Curve 
-- Can get complicated
-
-## Programming Language Level
-
-Most programming languages have package managers that specify the dependencies or libraries that a developer must have before running the app in a standardized development environment.  
-
-The package managers usually store that info in a file.
-
-Here are some for the most popular programming languages:
-- [requirements.txt](https://learnpython.com/blog/python-requirements-file/)
-- [package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
-- [pom.xml](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html)
-
-## App Level
-
-Similar to the programming language file, an app may store its dependencies needed to run the app in a standardized development environment in a file.
-
-An example of an app having a package manager that stores its dependencies in a `values.yml` file is Kubernetes's [Helm](https://helm.sh/docs/chart_template_guide/values_files/#helm)
+### 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.