Initial draft of blog contribution page #749
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Doug Erickson <dougeric@amazon.com>
erickson-doug
added
do-not-merge/in-review
Signed-off-by: Doug Erickson <dougeric@amazon.com>
Signed-off-by: Doug Erickson <dougeric@amazon.com>
Signed-off-by: Doug Erickson <dougeric@amazon.com>
Signed-off-by: Doug Erickson <dougeric@amazon.com>
erickson-doug
added
do-not-merge/preview-only
and removed
do-not-merge/in-review
erickson-doug
assigned erickson-doug and unassigned sptramer, OBWANDO, paucom and AMZN-Phil
|
SIG meeting notes: This PR will be reviewed by the SIG for any issues or updates to the blog policy. Members should complete comments by Sep. 3, 2021. |
AMZN-Liv
reviewed
Aug 30, 2021
|
|
||
| * Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is one thing; slagging on a similar product or another company is another. The latter will not be tolerated, regardless of how strongly you feel on the subject. | ||
|
|
||
| * Get too egotistical or too hyped. Choose your modifiers and adverbs with care to not oversell (or undersell) anything. Also, while a blog series can really help your resume (if done thoughtfully), the O3DE blog is ultimately about, well, O3DE. Not you. |
There was a problem hiding this comment.
While I do understand the sentiment of the last sentences here, it reads a bit defensive to me and unrelated to the parts about over/underselling the message you're presenting in the post. Is it necessary, given that the first "Do" is about keeping it on topic to O3DE as well? Could we strengthen that point, perhaps, and keep this last one focused on how to craft a humble message?
There was a problem hiding this comment.
Agreed. Rewriting!
JwGedit
requested changes
Sep 17, 2021
|
|
||
| In contrast, technical documentation is "durable" (although much of it requires active update and maintenance). When you have a content idea, ask yourself: Is this ephemeral or opinionated content? If so, it's a blog post. If it's durable and focuses on understanding and using the product, it may be a better fit in the technical docs. If you're unsure, ask **sig-docs-community** on Discord or the sig mailing list. | ||
|
|
||
| To draft and submit a blog post, you will need: |
There was a problem hiding this comment.
Suggested change
| To draft and submit a blog post, you will need: | |
| To draft and submit a blog post, you need: |
|
|
||
| 2. Clone your fork to your local machine. Set `upstream` to o3de.org and `origin` to your fork. | ||
|
|
||
| 3. Create a branch (preferably one specific to JUST your blog post) for submission. |
There was a problem hiding this comment.
Suggested change
| 3. Create a branch (preferably one specific to JUST your blog post) for submission. | |
| 3. Create a branch for submission. Preferably a branch that is specific to only your blog post. |
|
|
||
| 3. Create a branch (preferably one specific to JUST your blog post) for submission. | ||
|
|
||
| 4. Open your editor of choice and create a draft post using Markdown under thr `/content/blog/posts` folder. Give it a clear, unique filename in all lower-case, with no spaces. (Please use a hyphen `-` as a replacement for spaces. Avoid all other non-alphanumeric characters.) |
There was a problem hiding this comment.
Suggested change
| 4. Open your editor of choice and create a draft post using Markdown under thr `/content/blog/posts` folder. Give it a clear, unique filename in all lower-case, with no spaces. (Please use a hyphen `-` as a replacement for spaces. Avoid all other non-alphanumeric characters.) | |
| 4. Open your editor of choice and create a draft post using Markdown under the `/content/blog/posts` folder. Give it a clear, unique filename in all lowercase, with no spaces. (Use a hyphen `-` as a replacement for spaces. Please do not use any other non-alphanumeric characters.) |
| weight: 600 | ||
| --- | ||
|
|
||
| Blog posts are an important and semi-formal way to deliver announcements, insights, learnings, and professional opinions for the O3DE org and the greater public. Part of growing as a community is establishing a strong blog presence, and we'd love for you to contribute! Here's how. |
There was a problem hiding this comment.
Suggested change
| Blog posts are an important and semi-formal way to deliver announcements, insights, learnings, and professional opinions for the O3DE org and the greater public. Part of growing as a community is establishing a strong blog presence, and we'd love for you to contribute! Here's how. | |
| Blog posts are an important and semi-formal way to deliver announcements, insights, learnings, and professional opinions for the **Open 3D Engine (O3DE)** org and the greater public. Part of growing as a community is establishing a strong blog presence, and we'd love for you to contribute! Here's how. |
|
|
||
| * O3DE strategy, **if** you are actively participating in a SIG around feature or product strategy, **and** have the approval of a SIG. | ||
|
|
||
| * Interviews with, or profiles of, important and established community members. People put a human face on a technical product, and the world reliably likes to hear humans say they have to say. In this case, it should be professional observations, knowledge, and commentary—and shuld be specifically related to O3DE. Personal opinions, as ever, should be largely technical. |
There was a problem hiding this comment.
Suggested change
| * Interviews with, or profiles of, important and established community members. People put a human face on a technical product, and the world reliably likes to hear humans say they have to say. In this case, it should be professional observations, knowledge, and commentary—and shuld be specifically related to O3DE. Personal opinions, as ever, should be largely technical. | |
| * Interviews with, or profiles of, important and established community members. People put a human face on a technical product, and the world reliably likes to hear humans say what they have to say. In this case, it should be professional observations, knowledge, and commentary—and shuld be specifically related to O3DE. Personal opinions, as ever, should be largely technical. |
|
|
||
| * Include images and diagrams wherever appropriate. | ||
|
|
||
| * Consider your audience, which is diverse across many sociocultural and industry axes. Choose your words with respect and care, and be prepared to take feedback sincerely and make changes. No-one knows everything about the folks in the community and the industry, so don't let some initially careless wording caught in review bring you down; just make the changes, internalize the feedback, and keep delivering great content! |
There was a problem hiding this comment.
Suggested change
| * Consider your audience, which is diverse across many sociocultural and industry axes. Choose your words with respect and care, and be prepared to take feedback sincerely and make changes. No-one knows everything about the folks in the community and the industry, so don't let some initially careless wording caught in review bring you down; just make the changes, internalize the feedback, and keep delivering great content! | |
| * Consider your audience, which is diverse across many sociocultural and industry axes. Choose your words with respect and care, and be prepared to take feedback sincerely and make changes. No one knows everything about the folks in the community and the industry, so don't let some initially careless wording caught in review bring you down. Make the changes, as appropriate, and keep delivering great content! |
|
|
||
| * Get political. Politics pervade every part of life, and we all have different backgrounds, ideologies, and reactions to the way in which culture and society shapes itself. The O3DE blog isn't the place for it, unless you are running a community-approved political initiative and have the blessings of the Linux Foundation. | ||
|
|
||
| * Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is one thing; slagging on a similar product or another company is another. The latter will not be tolerated, regardless of how strongly you feel on the subject. |
There was a problem hiding this comment.
Suggested change
| * Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is one thing; slagging on a similar product or another company is another. The latter will not be tolerated, regardless of how strongly you feel on the subject. | |
| * Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is one thing; however, slagging on a similar product or another company is another. The latter will not be tolerated, regardless of how strongly you feel on the subject. |
Suggested rewrite: Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is fine. Slagging on a similar product or another company is not.
|
|
||
| **Don't:** | ||
|
|
||
| * Get personal. We have no tolerance for using the O3DE blog to call out community individuals—or any individuals, really—in any negative way, no matter how concerned you are. |
There was a problem hiding this comment.
Suggested change
| * Get personal. We have no tolerance for using the O3DE blog to call out community individuals—or any individuals, really—in any negative way, no matter how concerned you are. | |
| * Get personal. We have no tolerance for using the O3DE blog to call out community individuals—or any individuals, really—in any negative way, no matter how concerned you are. |
Suggested rewrite: Get personal. Do not use the O3DE blog to call out any individuals in a negative way.
|
|
||
| * Get personal. We have no tolerance for using the O3DE blog to call out community individuals—or any individuals, really—in any negative way, no matter how concerned you are. | ||
|
|
||
| * Get political. Politics pervade every part of life, and we all have different backgrounds, ideologies, and reactions to the way in which culture and society shapes itself. The O3DE blog isn't the place for it, unless you are running a community-approved political initiative and have the blessings of the Linux Foundation. |
There was a problem hiding this comment.
Suggested change
| * Get political. Politics pervade every part of life, and we all have different backgrounds, ideologies, and reactions to the way in which culture and society shapes itself. The O3DE blog isn't the place for it, unless you are running a community-approved political initiative and have the blessings of the Linux Foundation. | |
| * Get political. Politics pervade every part of life, and we all have different backgrounds, ideologies, and reactions to the way in which culture and society shapes itself. The O3DE blog isn't the place for it, unless you are running a community-approved political initiative and have the blessings of the Linux Foundation. |
Suggested rewrite: Get political. The O3DE blog isn't the place for it, unless you are running a community-approved political initiative, and have the blessings of the Linux Foundation.
There was a problem hiding this comment.
Getting Docs to take a look on this to see if it should be changed or not.
|
|
||
| * Attack or criticize other products, platforms, or companies directly. Showing perf data between O3DE and a similar product/feature pairing is one thing; slagging on a similar product or another company is another. The latter will not be tolerated, regardless of how strongly you feel on the subject. | ||
|
|
||
| * Get too egotistical or too hyped. Choose your modifiers and adverbs with care to not oversell (or undersell) anything. Also, while a blog series can really help your resume (if done thoughtfully), the O3DE blog is ultimately about, well, O3DE. Not you. |
There was a problem hiding this comment.
Suggested change
| * Get too egotistical or too hyped. Choose your modifiers and adverbs with care to not oversell (or undersell) anything. Also, while a blog series can really help your resume (if done thoughtfully), the O3DE blog is ultimately about, well, O3DE. Not you. | |
| * Get too egotistical or too hyped. Choose your modifiers and adverbs with care to not oversell (or undersell) anything. Also, while a blog series can really help your resume (if done thoughtfully), the O3DE blog is ultimately about, well, O3DE. Not you. |
Suggested rewrite: Exaggerate or overstate your points. Choose your modifiers and adverbs carefully to not oversell, or even undersell, anything. Also, while a blog series can really help your resume (if you do it thoughtfully), the O3DE blog is ultimately about, well, O3DE.
8 tasks
sptramer
reviewed
Sep 21, 2021
|
|
||
| **Do:** | ||
|
|
||
| * Discuss O3DE! (Duh.) Go deep! Highly technical blog posts, in particular, establish community credibility and provide a resource for people looking for deeper knowledge beyond the tech docs. |
There was a problem hiding this comment.
Suggested change
| * Discuss O3DE! (Duh.) Go deep! Highly technical blog posts, in particular, establish community credibility and provide a resource for people looking for deeper knowledge beyond the tech docs. | |
| * Discuss O3DE! Go deep! Highly technical blog posts, in particular, establish community credibility and provide a resource for people looking for deeper knowledge beyond the tech docs. |
|
Need reviews for final update and edit by 10/4/2021 EoD (5 PM Pacific) |
sptramer
added
the
do-not-merge/hold
|
@erickson-doug We've hit the comment deadline a while back, going to address review so that we can do any necessary 2nd round edits and merge? |
Signed-off-by: Doug Erickson <dougeric@amazon.com>
sptramer
suggested changes
Oct 25, 2021
|
|
||
| 2. Clone your fork to your local machine. Set `upstream` to o3de.org and `origin` to your fork. | ||
|
|
||
| 3. Create a branch for submission. Preferably a branch that is specific to only your blog post. |
There was a problem hiding this comment.
Suggested change
| 3. Create a branch for submission. Preferably a branch that is specific to only your blog post. | |
| 3. Create a branch for submission. This branch should contain _only_ the necessary content additions for your blog post. |
Comment on lines
40
to
46
| title: "YOUR TITLE IN QUOTES HERE. KEEP IT LESS THAN 80 CHARACTERS." | ||
| date: YYYY-MM-DD | ||
| slug: UNIQUE STRING FOR YOUR POST | ||
| author: YOUR PREFERRED AUTHOR NAME HERE. EMPLOYER IS OPTIONAL! | ||
| blog_img: "/images/blog/YOUR-OPTIONAL-ASSOCIATED-IMAGE-THUMBNAIL-HERE" | ||
| full_img: "/images/blog/ YOUR-OPTIONAL-ASSOCIATED-FULL-IMAGE-HERE" | ||
| --- |
There was a problem hiding this comment.
Suggested change
| title: "YOUR TITLE IN QUOTES HERE. KEEP IT LESS THAN 80 CHARACTERS." | |
| date: YYYY-MM-DD | |
| slug: UNIQUE STRING FOR YOUR POST | |
| author: YOUR PREFERRED AUTHOR NAME HERE. EMPLOYER IS OPTIONAL! | |
| blog_img: "/images/blog/YOUR-OPTIONAL-ASSOCIATED-IMAGE-THUMBNAIL-HERE" | |
| full_img: "/images/blog/ YOUR-OPTIONAL-ASSOCIATED-FULL-IMAGE-HERE" | |
| --- | |
| title: The title of your blog post. Please keep it under 80 characters. | |
| date: YYYY-MM-DD | |
| slug: <Unique string for your post, usually a condensed form of the title> | |
| author: YOUR PREFERRED AUTHOR NAME HERE. EMPLOYER IS OPTIONAL! | |
| blog_img: "/images/blog/<optional thumbnail>" | |
| full_img: "/images/blog/<optional full image>" | |
| --- |
Comment on lines
52
to
59
| --- | ||
| title: "Announcing Open 3D Engine!" | ||
| date: 2021-07-06 | ||
| slug: welcome-post | ||
| author: Doug Erickson, Amazon Web Services | ||
| blog_img: "/images/blog/announcement_thumbnail.jpg" | ||
| full_img: "/images/blog/atom_showcase.png" | ||
| --- |
There was a problem hiding this comment.
Suggested change
| --- | |
| title: "Announcing Open 3D Engine!" | |
| date: 2021-07-06 | |
| slug: welcome-post | |
| author: Doug Erickson, Amazon Web Services | |
| blog_img: "/images/blog/announcement_thumbnail.jpg" | |
| full_img: "/images/blog/atom_showcase.png" | |
| --- | |
| --- | |
| title: Announcing Open 3D Engine! | |
| date: 2021-07-06 | |
| slug: welcome-post | |
| author: Doug Erickson, Amazon Web Services | |
| blog_img: "/images/blog/announcement_thumbnail.jpg" | |
| full_img: "/images/blog/atom_showcase.png" | |
| --- |
| --- | ||
| ``` | ||
|
|
||
| Note that the blog is automated and that the `date` field determines when the blog will first become visible if your pull request is accepted and merged. |
There was a problem hiding this comment.
Suggested change
| Note that the blog is automated and that the `date` field determines when the blog will first become visible if your pull request is accepted and merged. | |
| {{ note }} | |
| Blog posting is automated and that the `date` field determines when the blog will first become visible if your pull request is accepted and merged. | |
| {{ /note }} |
| 9. Go into the O3DE Discord server and share your pull request for review. (Alternatively, mail the sig-docs-community mailing list with a link.) Someone will review it and provide feedback or an okay. A maintainer will merge it when at least one reviewer approves it. We aim to get these posted quick, but since we rely on the community for feedback and review, you may need to drive reviews in the Discord server. | ||
|
|
||
| {{< note >}} | ||
| The O3DE Community reserves the right to not publish any blog post that does not meet our standards. We also reserve the right to remove any currently published blog post that might conflict with the agreed-upon O3DE strategy or delivery. |
There was a problem hiding this comment.
Suggested change
| The O3DE Community reserves the right to not publish any blog post that does not meet our standards. We also reserve the right to remove any currently published blog post that might conflict with the agreed-upon O3DE strategy or delivery. | |
| The O3DE Community reserves the right to not publish any blog post that does not meet our standards. We also reserve the right to remove any currently published blog post. |
There are lots of reasons to remove blog posts, and they should be done at the discretion of a number of committees. If we remove one erroneously and it's really bad, we'll get the roasting we deserve.
|
|
||
| Good question! That's really up to the community alongside our established Code of Conduct and Community Tenets. Not sure? Join the O3DE Discord or one of the SIGs, and vet your idea with our members. | ||
|
|
||
| Here's some basic Do's and Don'ts to help you scope your effort and avoid an obvious rejection. |
There was a problem hiding this comment.
Suggested change
| Here's some basic Do's and Don'ts to help you scope your effort and avoid an obvious rejection. | |
| Here's some basic Do's and Don'ts to help you focus your work and avoid rejection. |
|
|
||
| Here's some basic Do's and Don'ts to help you scope your effort and avoid an obvious rejection. | ||
|
|
||
| **Do:** |
There was a problem hiding this comment.
Suggested change
| **Do:** | |
| ### Do |
|
|
||
| * Consider your audience, which is diverse across many sociocultural and industry axes. Choose your words with respect and care, and be prepared to take feedback sincerely and make changes. No one knows everything about the folks in the community and the industry, so don't let some initially careless wording caught in review bring you down. Make the changes (as appropriate) and keep delivering great content! | ||
|
|
||
| **Don't:** |
There was a problem hiding this comment.
Suggested change
| **Don't:** | |
| ### Don't |
Comment on lines
179
to
184
| **NOTE**: If you are using a **macOS** platform for docs development, you must run Hugo Netlify with the `--watch=false` switch enabled. For example: | ||
|
|
||
| ```macos | ||
| hugo server --port 44541 --bind=0.0.0.0 --watch=false | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Suggested change
| **NOTE**: If you are using a **macOS** platform for docs development, you must run Hugo Netlify with the `--watch=false` switch enabled. For example: | |
| ```macos | |
| hugo server --port 44541 --bind=0.0.0.0 --watch=false | |
| ``` | |
| {{ note }} | |
| If you use the **macOS** platform for docs development, you must run Hugo with the `--watch=false` switch enabled. For example: | |
| ```bash | |
| hugo server --port 44541 --bind=0.0.0.0 --watch=false | |
| ``` | |
| {{ /note }} |
There was a problem hiding this comment.
@sptramer Pushed all requested fixes
erickson-doug
removed
the
do-not-merge/hold
Signed-off-by: Doug Erickson <dougeric@amazon.com>
FiniteStateGit
requested changes
Oct 26, 2021
|
@erickson-doug @AMZN-Liv - Is this still up to date and should it be merged to the site? Would we rather have this as marketing or sig-docs guidance, rather than for garden-variety contributors who are looking to add to docs? |
Yup, as far as I know, it's up-to-date on revisions based on the history above. |
Ugbot
reviewed
Feb 28, 2022
aFinchy
reviewed
Mar 14, 2022
|
Closed in favor of #1581 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Signed-off-by: Doug Erickson dougeric@amazon.com