From ad0aa968293a49972aa4200717a7110f5f1a2bc3 Mon Sep 17 00:00:00 2001 From: pogi7 Date: Mon, 17 Jun 2024 11:56:53 -0700 Subject: [PATCH] reformat documentation to better tie into the main point on the home page Signed-off-by: pogi7 --- README.md | 2 +- docs/advanced-tips/_category_.json | 2 +- docs/advanced-tips/agile-development.md | 49 ++++++--------- docs/advanced-tips/artificial-intelligence.md | 57 +++++------------ docs/advanced-tips/package-manager.md | 58 ++++-------------- .../standard-development-environment.md | 61 +++---------------- docs/advanced-tips/user-experience.md | 30 +++------ docs/intro.md | 27 +++++--- docusaurus.config.ts | 2 +- 9 files changed, 86 insertions(+), 202 deletions(-) diff --git a/README.md b/README.md index 2bfcf37..9df64aa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Developer Experience Tips +# Digital Transformation Tips ## Source Code Link to [Source Code](https://github.com/pogi7/dx-tips) diff --git a/docs/advanced-tips/_category_.json b/docs/advanced-tips/_category_.json index 3840ae9..4dfab7a 100644 --- a/docs/advanced-tips/_category_.json +++ b/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." } } diff --git a/docs/advanced-tips/agile-development.md b/docs/advanced-tips/agile-development.md index 9c02fb5..272f173 100644 --- a/docs/advanced-tips/agile-development.md +++ b/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) diff --git a/docs/advanced-tips/artificial-intelligence.md b/docs/advanced-tips/artificial-intelligence.md index a396757..eade423 100644 --- a/docs/advanced-tips/artificial-intelligence.md +++ b/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. diff --git a/docs/advanced-tips/package-manager.md b/docs/advanced-tips/package-manager.md index 6896612..ced5354 100644 --- a/docs/advanced-tips/package-manager.md +++ b/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 diff --git a/docs/advanced-tips/standard-development-environment.md b/docs/advanced-tips/standard-development-environment.md index 1d744c8..6d35a8d 100644 --- a/docs/advanced-tips/standard-development-environment.md +++ b/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. \ No newline at end of file diff --git a/docs/advanced-tips/user-experience.md b/docs/advanced-tips/user-experience.md index b94b23f..8387dbd 100644 --- a/docs/advanced-tips/user-experience.md +++ b/docs/advanced-tips/user-experience.md @@ -8,27 +8,15 @@ Spending some time to think about the user experience of the app will help impro 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. -## Get a Designer +### 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. -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. +### 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. -### Where to Find One +### 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. -Personal Project: -- Post on Reddit's web_design [subreddit](https://www.reddit.com/r/web_design/) -- This [Quora post](https://www.quora.com/How-can-I-hire-a-web-design-and-where-can-I-find-a-web-designer) can help with finding a designer - -Professional Project: -- Ask your supervisor if there is a design team in your organization - - If so then see your dev team has the budget to hire one - - If not then see if you can pitch the idea of starting a design team at your work - -## 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. - -### Figma - -[Figma](https://www.figma.com) is the industry standard app for designers to make designs for websites, 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. - -Figma can also be used to verify that your app meets accessibility requirements such as ensuring that the app's colors works for people with color blindness. +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. diff --git a/docs/intro.md b/docs/intro.md index d3c70c3..029e49f 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -4,15 +4,21 @@ sidebar_position: 1 # Basic Tips -Let's discover the basics of pleasant and effective **developer experience in less than 5 minutes**. +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. -Version control can allow developer teams to keep track, mitigate, and resolve errors that may arise from code degradation or human error. +### 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. -### Git +### 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. + + ## 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. -Documentation helps dev teams onboard new developers much faster and prevent information from being lost due to turnover or forgetting. +### 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) -### Comments + \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index abf3cfc..bc231e2 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -3,7 +3,7 @@ import type {Config} from '@docusaurus/types'; import type * as Preset from '@docusaurus/preset-classic'; const config: Config = { - title: 'Developer Experience Tips', + title: 'Digital Transformation Tips', tagline: "A Hitchhiker's Guide to Pleasant and Effective DX", favicon: 'img/favicon.ico',