Docs

[rgardler-msft]

No description provided.

[Copilot]

Copilot reviewed 2 out of 3 changed files in this pull request and generated 7 comments.

Files not reviewed (1)

• scripts/test_ie.sh: Language not supported

Comments suppressed due to low confidence (2)

docs/README.md:17

• The phrase 'customer Portal interface' should be 'custom Portal interface'.

Innovation Engine is designed to be reused in custom user experiences. For example, Microsoft Azure uses Innovation Engine to provide documentation on their Learn site, which can also be executed in the Azure Portal. This allows users to explore 'good practice' documentation at the pace they prefer. They can simply read the documentation, they can interactively work through it in a customer Portal interface or they can simply go ahead and run it in order to deploy the architecture described within the document.

README.md:36

• Typo ('excercise' should be 'exercise'). Suggestion: 'As an exercise, if you have checked out the Innovation Engine code you could edit the echo statement above, whilst not updating the results block.'

As an excercise, if you have checked out the Innovation Engine code you could edit the echo statement above, whilst not updating the results block.

[Copilot]

The phrase 'executed interacted with an executed' is incorrect. It should be revised for clarity.

Suggested change

	Executable Documentation is a shell script, leveraging any tools available in the shell and embedding it within documentation. That is, it takes standard markdown language and amplifies it by allowing the code commands within the document to be executed interacted with an executed.
	Executable Documentation is a shell script, leveraging any tools available in the shell and embedding it within documentation. That is, it takes standard markdown language and amplifies it by allowing the code commands within the document to be executed and interacted with.

[Copilot]

The phrase 'you documentation' should be 'your documentation'.

Suggested change

* Describe the intent and expected behaviour of your shell scripts in markdown rather than comments. This means you documentation can contain hyperlinks, images, formatting etc. It can be rendered as standard markdown, e.g. as a `README.md` or a wiki page in GitHub, or as a web page. It also means that there is no need to keep two separate documents in sync. Editing code and documentation is now done in a single file.

* Describe the intent and expected behaviour of your shell scripts in markdown rather than comments. This means your documentation can contain hyperlinks, images, formatting etc. It can be rendered as standard markdown, e.g. as a `README.md` or a wiki page in GitHub, or as a web page. It also means that there is no need to keep two separate documents in sync. Editing code and documentation is now done in a single file.

[Copilot]

The word 'excercise' is misspelled. It should be 'exercise'.

Suggested change

	As an excercise, if you have checked out the Innovation Engine code you could edit the echo statement above, whilst not updating the results block. When you run `ie test scripts/README.md` this code will then fail. Not very useful, but a good first example of how you can improve the quality of your documentation and scripts through testing with Innovation Engine.
	As an exercise, if you have checked out the Innovation Engine code you could edit the echo statement above, whilst not updating the results block. When you run `ie test scripts/README.md` this code will then fail. Not very useful, but a good first example of how you can improve the quality of your documentation and scripts through testing with Innovation Engine.

[Copilot]

Grammar error. Suggestion: 'allowing the code commands within the document to be executed and interacted with.'

Suggested change

	Executable Documentation is a shell script, leveraging any tools available in the shell and embedding it within documentation. That is, it takes standard markdown language and amplifies it by allowing the code commands within the document to be executed interacted with an executed.
	Executable Documentation is a shell script, leveraging any tools available in the shell and embedding it within documentation. That is, it takes standard markdown language and amplifies it by allowing the code commands within the document to be executed and interacted with.

[Copilot]

Typo ('you' should be 'your'). Suggestion: 'This means your documentation can contain hyperlinks, images, formatting etc.'

Suggested change

* Describe the intent and expected behaviour of your shell scripts in markdown rather than comments. This means you documentation can contain hyperlinks, images, formatting etc. It can be rendered as standard markdown, e.g. as a `README.md` or a wiki page in GitHub, or as a web page. It also means that there is no need to keep two separate documents in sync. Editing code and documentation is now done in a single file.

* Describe the intent and expected behaviour of your shell scripts in markdown rather than comments. This means your documentation can contain hyperlinks, images, formatting etc. It can be rendered as standard markdown, e.g. as a `README.md` or a wiki page in GitHub, or as a web page. It also means that there is no need to keep two separate documents in sync. Editing code and documentation is now done in a single file.

[Copilot]

Typo ('reslts' should be 'results'). Suggestion: 'Since Innovation Engine can test the actual results of an execution against the intended results, this means our documentation is also part of our test suite.'

Suggested change

	Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the actual results of an execution against the intended reslts this means our documentation is also part of our test suite. In our `scripts` folder you will find a `test_ie.sh` script. Running this will run through all of our documentation in test mode.
	Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the actual results of an execution against the intended results, this means our documentation is also part of our test suite. In our `scripts` folder you will find a `test_ie.sh` script. Running this will run through all of our documentation in test mode.

[Copilot]

Typo ('tun' should be 'run'). Suggestion: 'we would encourage you to run the full test suite before issuing a PR.'

Suggested change

	If you make any changes to the IE code (see Contributing below) we would encourage you to tun the full test suite before issuing a PR.
	If you make any changes to the IE code (see Contributing below) we would encourage you to run the full test suite before issuing a PR.