diff --git a/versioned_docs/version-v1.0.0/advanced-tips/_category_.json b/versioned_docs/version-v1.0.0/advanced-tips/_category_.json new file mode 100644 index 0000000..3840ae9 --- /dev/null +++ b/versioned_docs/version-v1.0.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 Developer Experience." + } +} diff --git a/versioned_docs/version-v1.0.0/advanced-tips/agile-development.md b/versioned_docs/version-v1.0.0/advanced-tips/agile-development.md new file mode 100644 index 0000000..9c02fb5 --- /dev/null +++ b/versioned_docs/version-v1.0.0/advanced-tips/agile-development.md @@ -0,0 +1,55 @@ +--- +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 + +[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 + +::: + + +## 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 + +Cons: +- Meeting heavy +- Required roles such as scrum master, product owner, etc. + + +## 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 + +## 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. + +- 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) diff --git a/versioned_docs/version-v1.0.0/advanced-tips/artificial-intelligence.md b/versioned_docs/version-v1.0.0/advanced-tips/artificial-intelligence.md new file mode 100644 index 0000000..a396757 --- /dev/null +++ b/versioned_docs/version-v1.0.0/advanced-tips/artificial-intelligence.md @@ -0,0 +1,58 @@ +--- +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 + +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. + +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. + +:::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) + +## 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. + + +### Database + +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. diff --git a/versioned_docs/version-v1.0.0/advanced-tips/package-manager.md b/versioned_docs/version-v1.0.0/advanced-tips/package-manager.md new file mode 100644 index 0000000..6896612 --- /dev/null +++ b/versioned_docs/version-v1.0.0/advanced-tips/package-manager.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 3 +--- + +# Package Managers + +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) diff --git a/versioned_docs/version-v1.0.0/advanced-tips/standard-development-environment.md b/versioned_docs/version-v1.0.0/advanced-tips/standard-development-environment.md new file mode 100644 index 0000000..1d744c8 --- /dev/null +++ b/versioned_docs/version-v1.0.0/advanced-tips/standard-development-environment.md @@ -0,0 +1,65 @@ +--- +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. + +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 + +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) diff --git a/versioned_docs/version-v1.0.0/advanced-tips/user-experience.md b/versioned_docs/version-v1.0.0/advanced-tips/user-experience.md new file mode 100644 index 0000000..b94b23f --- /dev/null +++ b/versioned_docs/version-v1.0.0/advanced-tips/user-experience.md @@ -0,0 +1,34 @@ +--- +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. + +## 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. + +### Where to Find One + +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. diff --git a/versioned_docs/version-v1.0.0/intro.md b/versioned_docs/version-v1.0.0/intro.md new file mode 100644 index 0000000..d3c70c3 --- /dev/null +++ b/versioned_docs/version-v1.0.0/intro.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +--- + +# Basic Tips + +Let's discover the basics of pleasant and effective **developer experience in less than 5 minutes**. + +## Version Control + +[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. + +### 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 + +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. + +### 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) \ No newline at end of file diff --git a/versioned_sidebars/version-v1.0.0-sidebars.json b/versioned_sidebars/version-v1.0.0-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/versioned_sidebars/version-v1.0.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/versions.json b/versions.json new file mode 100644 index 0000000..60ca140 --- /dev/null +++ b/versions.json @@ -0,0 +1,3 @@ +[ + "v1.0.0" +]