What's your strategy for web application workflow and documentation?

My strategy for web application workflow and documentation typically involves the following steps: Requirement Gathering: Understand the project requirements thoroughly, including features, functionalities, and user expectations. Planning and Design: Create a detailed plan outlining the architecture, technologies, and design considerations for the web application. Development: Implement the web application according to the plan Testing: Conduct thorough testing to ensure that the web application functions correctly. Deployment: Deploy the web application to the appropriate environment Documentation: Document the entire development process Maintenance and Updates: Continuously monitor and maintain the web application

Defining the right goals and scope is crucial for the success of a project. When the scope is too broad or the goals are too vague, you may encounter unexpected results. This issue becomes even more problematic when there is a contradiction between the defined goals and scope. This can arise due to various root causes, such as misunderstandings, conflicting visions among stakeholders, or corporate politics. In such cases, the project manager must become an integration point for stakeholders, helping them find common ground and build a shared vision. Sometimes, it may result in a separate project involving mocking possible solutions, prototyping, interviewing stakeholders, and defining the main project outcomes.

Let’s delve into strategies for web application workflow and documentation. Workflow Strategy: Gather requirements. Design and wireframe. Develop incrementally. Test thoroughly. Deploy and maintain. Documentation Strategy: User, technical, and process docs. Tools: Process Street, Smartsheet, Word, flowchart software. Be comprehensive and keep it updated.

Here's a concise strategy for web application workflow and documentation: Gather requirements. Plan, design, and develop the application. Test thoroughly. Deploy to production. Document workflow, architecture, and instructions. Provide user training and support. Maintain, update, and iterate as needed.

One thing that I would emphasise here is to document the tools and technologies selection. Usually any high level design document or similar document should add details about all tools and technologies used in the application/system. This should include all tools used in various activities such as project management, development, testing , build and deployment activities, etc. Plethora of tools are currently available. For example, tools are used for load testing, performance testing, security scanning and testing, static code analysers, various cloud services, etc. For certain tools or technologies, it is worth mentioning why a particular choice is made so that anyone referring the documentation in future is aware about the choice.

It is important to think about information architecture. In other words, think about how to organize the content of your website for live application. Each page should have a name and a description, and each page should have a specific content and responsibility.

Also mentioning that not everything has to go through Atlassian or SharePoint. Instead both GitHub and Gitlab (not sure about Bitbucket) provide the "issues" functionality which is even better suited for strategic products that are driven by strong engineering teams instead of product focussed project managers. The fact that de-facto all open source task planning runs on this feature in GitHub proves that it should not be discarded just because it may seem that it is not user friendly at first sight for non techies.

- Choosing tools is a strategic process. - Align choices with project requirements. - Consider compatibility, security, performance, and scalability. - Well-thought-out tool selection contributes to efficiency and success. - Leverage version control and project management tools for seamless collaboration.

Lots of tools & technologies out there to help. All of them are great in their own way. Yes get suggestions from others but try and find the best one suited for you. In my personal experience, Jetbrain IDEs, ApiDog (also the light weight alternative: Insomnia), VSCodium etc. are some of the best that gets the most work done efficiently.

Everyone can write a code which machine can understand, focus should be to write the code that human can understand. Clean, precise and modular code is easy to maintain and troubleshoot. Code documentation should be provided for functionality understanding.

Any tool is only good for the application when used the right way. To begin with identify the coding standard and style guide for the rules and conventions for naming, formatting, commenting, and structuring required by your application code and pick up the tool accordingly. Maintenance of coding standards and style guide helps to keep them effective in the long run. Updating the rules with the newer needs, upgrading the tool itself and having it as part of the onboarding process help the purpose of having the correct guidelines followed.

A coding standard and style guide are strategic investments in the quality and longevity of a software project. They align team members, enhance code readability, and contribute to error reduction and efficient debugging. Tools such as Prettier, ESLint, and Stylelint automate the enforcement of coding standards, ensuring consistent best practices. Platforms like CodePen and CodeSandbox aid collaboration by providing spaces for developers to share and test code snippets. Embracing a coding standard reflects a commitment to excellence, collaboration, and continuous improvement. In the dynamic world of software development, a robust coding standard is a guiding light that ensures code consistency, readability, and long-term success.

Stackblitz should definitely be mentioned here as well. It should be pointed out that while eslint is also used (or abused) for formatting, its main focus is on code style whereas prettier is 100% about formatting. Linter and formatter are not the same thing. Also, consistent formatting doesn't help at all when debugging, it's somehow just a matter of taste, whereas linting rules really help avoiding constructs considered harmful, e.g. not using the eval function in JavaScript, or preferring variable declarations with let and const instead of var.

My view about coding standards and style guides is that they matter much less than what people like to claim. They only really matter in one situation: when none is followed. Following a coding style doesn't mean that the codebase will be maintainable but not following a coding style ensures that the codebase will eventually become unmaintainable. Using tools like prettier or ESLint (in the js world) or other alternatives for different languages will allow you to remove one point of friction in a codebase with many contributors. It is not about the code standards and style guides, it's about following one.

The best advice I have received regarding documentation is to do it before you code. It helps you plan your approach better and makes it easier to stay on track of the purpose of the code where not documenting or doing so after the work makes one vulnerable to distraction on minor facets that are low value. The argument against documentation is that it gets out of date. If it is stored outside the code, have a comment in the code to remind developers where the documentation is and to update it if updating the code. It is also helpful to make it a habit to revise the documentation at the completion of work, accepting the reality that approaches change and incorrect documentation will frustrate the next developer, which may be yourself.

Put your documentation nearest to the artifacts it describes. It's easy for Confluence or Notion to get out of date, but if your documentation resides in the codebase, it's more likely to get the attention and eyeballs it is intended to get. We're big fans of markdown, and, where needed, static site generators, so that there is minimal friction for engineers to keep the documentation up to date.

Typescript should be mentioned here. While its original intention was adding strong typing to JavaScript (not documenting in the narrow sense), it has come a long way and now even serves the purpose of documenting the structure of backend responses. This is particularly useful in apps where the backend uses Node. The types can then be extracted to a single source of truth that can be then referenced both in the frontend and backend code. Vitepress should also be mentioned. Storybook and its alternatives, such as Histoire should also be in the list since it is the de-facto standard for documenting design systems and UI component libraries

Documentation is not an ancillary task but a strategic imperative in web application development. It bridges the divide between code and comprehension, fostering collaboration, reducing errors, and enhancing the overall development experience. The tools available, such as JSDoc, Sphinx, and Docusaurus, empower developers to not only create but also effectively disseminate documentation. Embracing a culture of continuous documentation, where clarity and user-friendliness are paramount, ensures that documentation remains a living, breathing entity that propels the success and longevity of web applications in an ever-evolving technological landscape.

-Documentation Thoroughly document the codebase with comments, README files, and documentation generators like JSDoc. Keep API documentation up to date.

Testing is possibly the most crucial part of the process that most organizations ignore or take for granted. Writing test cases can go a long way; in the long run, it ensures stability and reduces the cost of testing the software manually. Although it does not guarantee that there will be no bugs in the system, you go into deployments with a certain level of confidence. I'm not saying that in every circumstance we should write them; time and money play important roles as well! However, if we expect to provide long-term support for the software, we should definitely consider writing test cases. For debugging, setting up a third-party tool like Sentry can go a long way to identify and resolve issues quickly!

Playwright should be mentioned before all the other tools since it is the state-of-the-art tool for end-to-end testing nowadays. Vitest also deserves mention. Also describing the different types of tests. (unit, ui-component, integration, end-to-end) And coverage tools should be mentioned as well

Testing and debugging are not mere checkboxes in the development lifecycle; they are integral processes that define the quality, reliability, and success of a web application. The synergy between these processes, supported by an arsenal of powerful tools and methodologies, ensures that developers can navigate the complexities of coding with confidence. Continuous integration, automation, and a commitment to best practices further elevate the effectiveness of testing.

-Unit Testing: This involves testing individual components or functions of your code in isolation. Use testing frameworks like Jest for JavaScript or Pytest for Python to write unit tests. -Integration Testing: Check if different parts of your application work well together. Ensure that different modules or services communicate as expected. -End-to-End Testing (E2E): These tests simulate real user interactions with your application. Tools like Selenium, Puppeteer, or Cypress can be used to automate E2E tests. -Manual Testing: Don't underestimate the value of manual testing. As a developer, you can manually test your code to catch obvious issues and usability problems.

As a young Ukrainian developer, I remember the cold nights diving into code, chasing elusive bugs. To my fellow juniors, never underestimate the significance of testing. It’s not just about spotting errors, but ensuring our creations shine with quality. Embrace tools like Mocha or Jest; they’ve been my flashlight in the dark coding nights. Document everything: each test, each result. Remember, every error caught is a user saved. Keep pushing, and let’s craft web apps we’re proud of.

I believe this should be number one on the list. One of the first things we should be doing when setting up a web application is deploying it to production and/or staging if you are going to have one. This means that we’ll need not only the deployment, but also the CI/CD system set up. Nothing is worse than creating a web application that works completely on our system locally, and then having trouble getting it to deploy because our environment doesn’t match production. Then a lot of rework needs to take place. This is much better to discover and rectify at the time of development instead of after.

Blackduck and Datadog should be there. Also Gitlab CI and Bitbucket Pipelines. TrackJS might be considered useful as well. Monorepo tools like Nx, Lerna and Turborepo should be here as well

Curious not to see Azure Devops / Pipelines mentioned. It's so great when you commit some code to git, and it's already building in the background, ready to be put on the test server so you easily resolve the issue of "works on my machine" without having to manually execute all these steps. It also helps avoid user error because you missed a step somewhere. I've also had good experience with having a separate test pipeline, and not include your tests in the build pipeline, so that you can get a critical fix out of the door fast, but you still keep an eye on your tests. I know some will say that not all tests passing will mean you cannot deploy ever, but if you have a lot of tests this can really backfire when time is of the essence.

Web application development is not just about coding and designing. It’s also about deploying and maintaining. It’s about making your web application accessible and reliable to your users, and keeping it updated and secure. There are some great tools to assist, such as Heimdal Security Patch & Asset Management, Google Cloud Deployment Manager, or Jenkins for hosting, automation, and patching, Google Analytics, Hotjar, or Mixpanel for analytics, and npm, Dependabot, or Snyk for updates. These tools will help make your life easier and your web application better.

Design is key 🔑 to building great products. The industry is pivoting from building MVPs ( Minimum Viability ) to MLP ( Minimum Lovable Product ) - Delighting users is the centrepiece of any product and everything else assumes shapes size and form to cater to that one purpose - customer delight !

Workflows are different for different organizations. For startups, the focus is more on getting things done in a shorter time than in the process. For an established organization, the focus is more on the process, with increased tests. In an ideal case, the flow involves: 1. Discovery and Design 2. Architecting the process and product 3. Implementation with the necessary skilled engineers 4. Automation of different processes involving CI/CD and tests 5. Code -> Local Tests -> Dev Tests -> QA Tests -> Staging Tests -> UAT Validation -> Production Release for GA 1. Onboarding Documentation 2. Process Documentation 3. Setup Documentation 4. Feature Documentation 5. Release Documentation 6. Coding Standards Documentation

Few more key steps to consider: Security Documentation: Document security measures and best practices. Include information on how data is stored, encrypted, and secured. User Manuals: Create user manuals or help documentation to guide users on how to use the application effectively. Change Management: Document the process for handling updates, patches, and changes to the application. Disaster Recovery: Plan for disaster recovery and document the procedures to follow in case of data loss or system failure. Feedback and Continuous Improvement: Encourage feedback from users and team members to identify areas for improvement in the application and its documentation.

Documentation needs to be simple, I worked with teams where the developers had absolutely no industry experience. All changes been made to the system had to be fully documented by the end user. As I had industry specific knowledge I was able to catch any badly documented change requests that would have resulted in functionally correct code but it also been useless to the end user

Performance also needs to be considered a feature that needs to be defined. That’s not always as simple as just picking a number. Usually near the end of a milestone the products gets used under realistic dataset sizes and there are various performance issues that “couldnt have been foreseen” Performance needs to be “designed” up front along with realistic datasets so that the numbers have meaning and that the product can be tested appropriately during development.