Use desired language in migration guide template#18576
Use desired language in migration guide template#18576alice-i-cecile merged 4 commits intobevyengine:mainfrom
Conversation
alice-i-cecile
added
C-Docs
Co-authored-by: Miles Silberling-Cook <[email protected]>
| - Make sure it's searchable by directly naming the types and methods involved. | ||
| - Use backticks for types, methods and modules (e.g. `Vec<T>` or `core::mem::swap`). | ||
| - Use bullet points to explain complex changes. | ||
| - Avoid headings. If you must, use only level-two headings. |
There was a problem hiding this comment.
It's unrelated to this PR, but I though @NthTensor said this would be handled with tooling. So we don't impose any heading level, the user start using H1, then H2, etc. and the export/import tool will convert to the proper level. The only limit we should impose is "don't use more than X levels" (I think it was worded like that at some point).
There was a problem hiding this comment.
The markdown linter wants us to use level-2 because of the title in the front matter. No idea how to change that.
Pnoenix
left a comment
Pnoenix
left a comment
There was a problem hiding this comment.
These changes look fine. Maybe add another file or a section in here, that showcases what a complete migration guide file looks like?
In most cases, looking at sibling migration guides will be best for this :) |
alice-i-cecile
added
S-Ready-For-Final-Review
4 participants
Objective
Both reading and writing migration guides is easier when the language is standardized.
However, migration guide authors don't have clear guidelines for the tone and phrasing to use.
Solution
Communicate this information to authors by creating stub text with a clear and polite standard style.
We could instead write a style guide, but turning style guides into a writing style is slower and much harder than simply filling in the blanks. While style guides are a good fit for more free-form writing, they don't work well for the very mechanical and dry migration guides.