Conversation
MarkvanMents
left a comment
MarkvanMents
left a comment
There was a problem hiding this comment.
Hi Dana,
This looks really good - and a great advance for us in helping AI to provide good responses.
I have made a lot of comments, but I think a lot of them might need time to test and refine.
Have a look and see if there is anything that you think would be an improvement now. Perhaps make a Jira epic to help us track the refinement of specific aspects (as well as allowing for improvements as we use it).
But I think it is good to get this out there quickly and work with it to see which bits work well and whether some more refinement is needed.
But thanks for bringing your expertise and adding some consistency to our application of AI to the repo.
| description: Add new content to a page without rewriting existing content. | ||
| --- | ||
|
|
||
| Prompt the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Avoid making changes to existing content unless necessary for clarity or coherence when adding the new content. |
There was a problem hiding this comment.
I'll ask some questions here about your experience with prompting. I don't know the answers, but perhaps we could do some experimenting. (Is it possible to turn on a thinking mode in CoPilot so we can see how it is responding to the prompt - a quick google implies that it might be, but I'm not sure.
Anyhow, my question is around "Avoid". I wondered whether "Only make changes to existing content if necessary for clarity or coherence when adding the new content." would be more forceful?
There was a problem hiding this comment.
Is the idea that this is for internal use? Is there a way that we can encourage/force contributors to use this when adding new content?
| description: Edit the text, including reorganization and rephrasing. | ||
| --- | ||
|
|
||
| Perform holistic improvements, including reorganization and stronger phrasing, while preserving original intent. This goes beyond basic proofreading and polishing to enhance the overall quality and impact of the text. Consider restructuring sentences, paragraphs, or sections for better flow, replacing weak words with stronger alternatives, and improving clarity and consistency while maintaining the original meaning. However, avoid making changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. No newline at end of file |
There was a problem hiding this comment.
Will this also use the copilot-instructions file to help it do this?
There was a problem hiding this comment.
These are all zero-shot prompts. Should we look at adding some one-shot prompts (perhaps later)? Perhaps something to put on our backlog?
|
|
||
| Then identify ways to further improve the clarity by making the document easier to read, scan, and understand, without moving paragraphs around, changing the meaning, or significantly increasing the length. This may include breaking up long sentences, adding subheadings, and improving word choice. Do not make changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. | ||
|
|
||
| Avoid changing any code samples directly, but flag any code issues or inconsistencies in the chat. No newline at end of file |
There was a problem hiding this comment.
I think this is a case for "Do not" rather than "Avoid"?
| * `button` – Link buttons with `color`, `href`, `text`, and optional `title` attributes. | ||
| * `icon` – Inline SVG icons stored in `static/mx-icons` (`name` required, optional `color`) for use in UI descriptions. | ||
| * `youtube` / `vidyard` – Embed videos by ID. | ||
| * `swaggerui` / `swaggerui-disable-try-it-out` – Render OpenAPI specs. |
There was a problem hiding this comment.
This only works with type: swagger - should we mention this?
| 4. **Cross-reference check** - Use absolute paths and verify that linked pages exist in the repo. | ||
| 5. **Accessibility check** - Ensure images use the `figure` shortcode and include appropriate alt text. | ||
| 6. **Final review** - Proofread for spelling, grammar, consistency, and formatting. | ||
| 7. **Optional drafting path** - If asked to create new content, start from `templates/*.md` and then follow the same checks above. |
There was a problem hiding this comment.
I think this should go in the next section?
|
|
||
| ### Page Layout | ||
|
|
||
| Use the existing template in `templates/release-notes-template.md` as a reference and ensure required fields are present and accurate. |
There was a problem hiding this comment.
Safer to say use the structure in the current document. I'm not sure we will be creating a completely new set of release notes without guiding copilot more from the request prompt?
|
|
||
| Use the existing template in `templates/release-notes-template.md` as a reference and ensure required fields are present and accurate. | ||
|
|
||
| * Use `## <version> {#anchor}` for each release, with a release date and optional download button. |
There was a problem hiding this comment.
This is only for Studio Pro release notes.
There was a problem hiding this comment.
I think I would leave this out for now? There are too many options and different styles.
Perhaps brainstorm it with the team and try to come up with a good description of what a release note looks like. Perhaps have two separate sets of instructions, one for Studio Pro release notes, and one for all the others.
2 participants
No description provided.