documentation posts - idmontie's Portfolio

/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    h2: "h2",
    ol: "ol",
    li: "li",
    h3: "h3",
    a: "a"
  }, props.components);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process."
    }), "\n", _jsx(_components.h2, {
      children: "Onboarding"
    }), "\n", _jsx(_components.p, {
      children: "When new members start, do you have processes and documentation in place to make onboarding easy?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Is your process written down?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them."
    }), "\n", _jsx(_components.h2, {
      children: "Environment Setup"
    }), "\n", _jsx(_components.p, {
      children: "Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems."
    }), "\n", _jsx(_components.p, {
      children: "☐ Is the preferred IDE documented?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?"
    }), "\n", _jsx(_components.p, {
      children: "☐ If there is a VPN, are all the VPN details documented?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Is the preferred Git usage documented? IE git-flow etc?"
    }), "\n", _jsx(_components.h2, {
      children: "README"
    }), "\n", _jsx(_components.p, {
      children: "Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:"
    }), "\n", _jsx(_components.p, {
      children: "☐ Does the README have all the steps to:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Download"
      }), "\n", _jsx(_components.li, {
        children: "Install"
      }), "\n", _jsx(_components.li, {
        children: "Run"
      }), "\n", _jsx(_components.li, {
        children: "Deploy"
      }), "\n", _jsx(_components.li, {
        children: "Test"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Clients, servers, databases, 3rd party systems are documented"
      }), "\n", _jsx(_components.li, {
        children: "Data flows between systems are documented"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐  API Documentation - How is the API documented? This is similar to the architecture section."
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "If your repo has components, is there a Storybook or similar site to document the interfaces?"
      }), "\n", _jsx(_components.li, {
        children: "If your repo has web APIs, is there a OpenAPI spec that can be viewed?"
      }), "\n", _jsx(_components.li, {
        children: "Other projects will want to document their APIs as well."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Documentation - do you have a link to how to get to the documentation?"
      }), "\n", _jsx(_components.li, {
        children: "Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Building and CI/CD"
    }), "\n", _jsx(_components.p, {
      children: "If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository."
    }), "\n", _jsx(_components.p, {
      children: "☐  Build Pipeline"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Can the app be built in one step?"
      }), "\n", _jsx(_components.li, {
        children: "Is the pipeline modern?"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐  CI/CD"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Is there a CI/CD runner?"
      }), "\n", _jsx(_components.li, {
        children: "Is it documented?"
      }), "\n", _jsxs(_components.li, {
        children: ["Are there lint guidelines?", "\n", _jsxs(_components.ol, {
          children: ["\n", _jsx(_components.li, {
            children: "Are they checked on the CI/CD?"
          }), "\n"]
        }), "\n"]
      }), "\n", _jsxs(_components.li, {
        children: ["Are there unit tests?", "\n", _jsxs(_components.ol, {
          children: ["\n", _jsx(_components.li, {
            children: "Are they run on every commit?"
          }), "\n"]
        }), "\n"]
      }), "\n", _jsx(_components.li, {
        children: "Are there pre-push and pre-commit hooks? You can use Husky to set these up"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Testing"
    }), "\n", _jsx(_components.p, {
      children: "As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Testing"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Is there a test pipeline"
      }), "\n", _jsx(_components.li, {
        children: "Are there unit tests"
      }), "\n", _jsx(_components.li, {
        children: "Are there automated code coverage reports?"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Bundle Sizes"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Make sure tree shaking is happening correctly"
      }), "\n", _jsx(_components.li, {
        children: "Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Performance"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsxs(_components.li, {
        children: ["Analyze your web app for pagespeed, lighthouse rating, and ", _jsx(_components.a, {
          href: "https://github.com/thecreazy/siteaudit",
          children: "a11y"
        })]
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "External Services"
    }), "\n", _jsx(_components.p, {
      children: "Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them."
    }), "\n", _jsx(_components.p, {
      children: "☐ CMS"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Are there a lot of text and content that is constantly updated?"
      }), "\n", _jsx(_components.li, {
        children: "Is there a CMS already implemented?"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Conclusion"
    }), "\n", _jsx(_components.p, {
      children: "This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive."
    }), "\n", _jsx(_components.p, {
      children: "I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process.</p>
<h2>Onboarding</h2>
<p>When new members start, do you have processes and documentation in place to make onboarding easy?</p>
<p>☐ Is your process written down?</p>
<p>☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them.</p>
<h2>Environment Setup</h2>
<p>Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems.</p>
<p>☐ Is the preferred IDE documented?</p>
<p>☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?</p>
<p>☐ If there is a VPN, are all the VPN details documented?</p>
<p>☐ Is the preferred Git usage documented? IE git-flow etc?</p>
<h2>README</h2>
<p>Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:</p>
<p>☐ Does the README have all the steps to:</p>
<ol>
<li>Download</li>
<li>Install</li>
<li>Run</li>
<li>Deploy</li>
<li>Test</li>
</ol>
<p>☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:</p>
<ol>
<li>Clients, servers, databases, 3rd party systems are documented</li>
<li>Data flows between systems are documented</li>
</ol>
<p>☐  API Documentation - How is the API documented? This is similar to the architecture section.</p>
<ol>
<li>If your repo has components, is there a Storybook or similar site to document the interfaces?</li>
<li>If your repo has web APIs, is there a OpenAPI spec that can be viewed?</li>
<li>Other projects will want to document their APIs as well.</li>
</ol>
<p>☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?</p>
<ol>
<li>Documentation - do you have a link to how to get to the documentation?</li>
<li>Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?</li>
</ol>
<h3>Building and CI/CD</h3>
<p>If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository.</p>
<p>☐  Build Pipeline</p>
<ol>
<li>Can the app be built in one step?</li>
<li>Is the pipeline modern?</li>
</ol>
<p>☐  CI/CD</p>
<ol>
<li>Is there a CI/CD runner?</li>
<li>Is it documented?</li>
<li>Are there lint guidelines?
<ol>
<li>Are they checked on the CI/CD?</li>
</ol>
</li>
<li>Are there unit tests?
<ol>
<li>Are they run on every commit?</li>
</ol>
</li>
<li>Are there pre-push and pre-commit hooks? You can use Husky to set these up</li>
</ol>
<h3>Testing</h3>
<p>As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?</p>
<p>☐ Testing</p>
<ol>
<li>Is there a test pipeline</li>
<li>Are there unit tests</li>
<li>Are there automated code coverage reports?</li>
</ol>
<p>☐ Bundle Sizes</p>
<ol>
<li>Make sure tree shaking is happening correctly</li>
<li>Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin</li>
</ol>
<p>☐ Performance</p>
<ol>
<li>Analyze your web app for pagespeed, lighthouse rating, and <a href="https://github.com/thecreazy/siteaudit">a11y</a></li>
</ol>
<h3>External Services</h3>
<p>Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them.</p>
<p>☐ CMS</p>
<ol>
<li>Are there a lot of text and content that is constantly updated?</li>
<li>Is there a CMS already implemented?</li>
</ol>
<h3>Conclusion</h3>
<p>This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive.</p>
<p>I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again.</p>


Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process.

## Onboarding

When new members start, do you have processes and documentation in place to make onboarding easy?

☐ Is your process written down?

☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them.

## Environment Setup

Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems.

☐ Is the preferred IDE documented?

☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?

☐ If there is a VPN, are all the VPN details documented?

☐ Is the preferred Git usage documented? IE git-flow etc?

## README

Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:

☐ Does the README have all the steps to:

1. Download
2. Install
3. Run
4. Deploy
5. Test

☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:

1. Clients, servers, databases, 3rd party systems are documented
2. Data flows between systems are documented

☐  API Documentation - How is the API documented? This is similar to the architecture section.

1. If your repo has components, is there a Storybook or similar site to document the interfaces?
2. If your repo has web APIs, is there a OpenAPI spec that can be viewed?
3. Other projects will want to document their APIs as well.

☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?

1. Documentation - do you have a link to how to get to the documentation?
2. Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?

### Building and CI/CD

If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository.

☐  Build Pipeline

1. Can the app be built in one step?
2. Is the pipeline modern?

☐  CI/CD

1. Is there a CI/CD runner?
2. Is it documented?
3. Are there lint guidelines?
    1. Are they checked on the CI/CD?
4. Are there unit tests?
    1. Are they run on every commit?
5. Are there pre-push and pre-commit hooks? You can use Husky to set these up

### Testing

As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?

☐ Testing

1. Is there a test pipeline
2. Are there unit tests
3. Are there automated code coverage reports?

☐ Bundle Sizes

1. Make sure tree shaking is happening correctly
2. Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin

☐ Performance

1. Analyze your web app for pagespeed, lighthouse rating, and [a11y](https://github.com/thecreazy/siteaudit)

### External Services

Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them.

☐ CMS

1. Are there a lot of text and content that is constantly updated?
2. Is there a CMS already implemented?

### Conclusion

This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive.

I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again.


Reviewing Your Frontend Applications