Update README.md

[nserway]

Updated the EVerest Demo README to improve readability, set-up instructions, and include mermaid diagrams of the various demonstrations that are included in the repository.

• The team re-designed the EVerest Demo README to improve: readability, flow of instructions, and showcasing demonstration capabilities.
• After various sessions with the JOET team we determined this would be the best design for the README based on logical flow of information and readability for user types across the EV ecosystem (i.e., varying levels of experience with EV charging + code comprehension).

@shankari, per your most recent comments, here are our additions + changes:

• [Added] end to end testing mermaid diagram with messages between Everest, Probe Module, and MQTT Broker and hyperlinked the diagram within the Demo Table
• [Removed] language surrounding running the demo scripts in the Docker Terminal
• [Added] language that directs the user to run the demo scripts in the machine's terminal
• [Removed] CP + PP + all granular ISO messages from the mermaid diagrams across the "Appendix Diagrams" section (in regards to comment on line 261-263)
• [Added] ISO 15118-2 and OCPP 2.0.1 documentation in a new section "Reference Material" to provide additional context on the message flow during charging session
• [Removed] The OCPP 1.6J demonstration pertinent additional functionality
• [Added] Added step-by-step guidelines for users to contribute demonstrations + update documentation to the demonstration repo
• [Conducted] Codacy Analysis check - fixed errors EXCEPT adding in an image to the.img but adding the file to this PR so the new PR owner can add it to the .img folder

[shankari]

@nserway as I have indicated earlier, I would like to see some additional discussion of the rationale behind the PR in the description.
What are the high level changes?
What was the related design discussion?
Why are the changes set up this way?

This is particularly important in this case because the main goal of the rewrite was to redesign the user interface and provide a template for future changes to follow.

Please also make sure to spellcheck, I am not sure we got all the errors.

[shankari]

why is this N/A?

[nserway]

We did not create a mermaid diagram for the E2E tests. Since there isn't a UI associated with the demonstration (or if there is, the demo is not functioning properly) it was difficult to visualize what a diagram would look like.

[shankari]

The mermaid diagram is not related to the UI. The mermaid diagram is set up to understand how the various software modules communicate with each other, and the E2E test clearly has modules working together for the testing.

[shankari]

I am not sure what you mean by this.

1. The Docker desktop terminal can be used to interact with running containers. It cannot be used to launch containers from a script.
2. And I am not sure why the Docker desktop terminal would give better results than (say) docker exec
3. Spelling mistake "runing"

[nserway]

1. This note was spun out of a conversation with Katie about the additional functionality of Linux systems (i.e., running a demo script directly in a Linux machine's terminal) I will remove this note for clarity as I do not think it adds significant value to the overall README + created confusion on your review.
2. See above.
3. Just ran a spell check across the whole document + updated!

[shankari]

I am arguing for not using the docker desktop terminal and instead, using the command line.

[shankari]

I am not sure what you mean by this.

Here's the full docker desktop window on my mac. I don't see any terminal at the bottom of the screen.

Also, note that, on linux, docker does not come with the desktop UI by default.

https://docs.docker.com/desktop/install/linux/ ("What is the difference between Docker Desktop for Linux and Docker Engine?") Docker Desktop for Linux requires a license for commercial use.

[nserway]

This is what the application looks like on my end, I paste the Demo Command inside of the terminal to get the containers to spin up. Not sure if that's how all users Docker applications UI looks.

Additionally, I will remove Linux system notes for clarity since they are causing confusion.

[shankari]

@nserway "works for me" is not a good basis for demo instructions. I assume you are using Windows for this. Even if it works on Windows, that is 1/3 of the common OSes.

You should retain the instructions that work for the 2/3 case, which is to run it from the terminal.

[shankari]

Are you sure that the simulator is actually sending these values? How have you verified this?

[shankari]

Is this supposed to cover CP and PP? If so, you need to define what this means somewhere?

[nserway]

Yes, the PP and CP checks are a part of this charging session as defined in the ISO 15118-2 documentation. https://www.typhoon-hil.com/documentation/typhoon-hil-software-manual/References/iso15118_protocol.html. We will make changes in the README to cite this documentation.

[shankari]

This is simpified at best and incorrect at worst. Is there a reason that we are not showing the full flow? What is the goal of the diagram, and what is the level of granularity that you are aiming for?

[nserway]

The goal of the diagram was to provide a high level (non-granular) illustration of what is being demonstrated across the Demos. I was aiming for a very simplified version of the charging session

[shankari]

If we want a high-level description, I would avoid using specific ISO names (StartTransactionReq) because that implies that those are the messages getting sent. You should instead use a high-level text description.

[shankari]

Why was this removed? From our discussion, we were expecting that people who contribute new functionality will create new demos and update the documentation. And one of the main goals of your improvements was to create and document the related process, which @the-bay-kay and I would use to make our upcoming changes. Where is that process?

[nserway]

@nserway as I have indicated earlier, I would like to see some additional discussion of the rationale behind the PR in the description.

What are the high level changes? The team re-designed the EVerest Demo README to improve: readability, flow of instructions, and showcasing demonstration capabilities.
What was the related design discussion? Unsure of the question here, I think you are referring to the internal working sessions we had to determine the best framework for this READE, let me know if I can clarify further.
Why are the changes set up this way? After various sessions with the JOET team we determined this would be the best design for the README based on logical flow of information and readability for user types across the EV ecosystem (i.e., varying levels of experience with EV charging + code comprehension).

[shankari]

@nserway can you please have the tech team review this before sending it back to me for review? Some of your comments have fairly simple technical solutions, and it would be the most effective use of my time to have them addressed first.

[shankari]

What was the related design discussion? Unsure of the question here, I think you are referring to the internal working sessions we had to determine the best framework for this READE, let me know if I can clarify further.
Why are the changes set up this way? After various sessions with the JOET team we determined this would be the best design for the README based on logical flow of information and readability for user types across the EV ecosystem (i.e., varying levels of experience with EV charging + code comprehension).

One of the goals of open-source software is transparency into the decision making process. So we don't just want to have a work product, we want to document the discussions and deliberation that went into the work product. So yes, we want to document what were the user types you considered, what assumptions you made for them...

[shankari]

This is not great, but it is an improvement over what we had before, so I am going ahead and checking this in now.