Home
Welcome to the rocm-blogs wiki!
In this user guide we will cover the process of creating a blog for the ROCm Blogs site covering writing style tips to the workflow process.
- Readers first. Recognize your blog’s readership and put them first: AMD Tech Blogs target the world. Widen the scope of your blog as much as possible.
- Consider your goals and deliverables. Outline clear and simple goals for your blog. These goals should be detailed and reflected throughout the blog, from the title onwards. Carefully align the blog's content with its goals, and make sure the blog delivers on its promise.
- Technical focus. AMD ROCm™ Tech Blogs' goal is ultimately to inform readers about the technical aspects of our technology and how it can be used, not to sell them our technology. Make sure your blog has a strong technical emphasis and focus, providing new technical knowledge, insight and know-how.
- Converse with your reader. Blogs must be extremely accessible, simple to read and to follow. Write your blog in conversational style: simpler terms and words, and shorter sentences and paragraphs are preferable.
- Use active voice. A blog is a call for action. Use active voice throughout the blog, your goal is to engage the reader, make them care about your blog's goals and content, whether it a how-to-guide, a case study or a new technical feature announcement.
- Provide adequate background information. Assume little about the technical background of your reader and instead provide information within the blog and by pointing to available resources. Tech blogs always stand on the shoulders of others: whenever possible link to other AMD tech blogs, AMD tech docs, and to external resources.
If unfamiliar with markdown syntax or if technical writers prefer working on a word doc there are a couple useful tools to help write in markdown or convert to it.
- Converting word doc to markdown using pandoc: Pandoc - index
- Guide to Markdown: Markdown Guide
When creating a new blog, the process begins with creating a new issue.
- In the navigation bar at the top of the repository click on "Issues" then select "New Issue".
- From the dropdown that appears select "Create a new blog post".
- Fill out the required information to create the issue, if successful, a PR will automatically be created. If unsuccessful you will be notified with a linter error of why the PR could not be created and you can adjust the info in the issue fields.
- Once the PR has been created navigate to it either by clicking the redirect link on the issue or hitting "Pull requests" in the navigation bar and finding it manually.
Great, now the blog has been created and is ready to start getting filled with content!
If using a markdown converter then once the markdown file is created, you can just copy the content in.
- To start writing the blog post, first navigate to the "Files changed" tab in the PR.
- Click in the README.md markdown file on the side bar, then hit the three dots on the right side of the page on the file highlighted in a blue border, and finally hit "Edit file".
- From here you can copy in markdown-based content or write directly into the blog file using appropriate styling guidelines and markdown syntax.
- Any figures used can be placed into the images folder from the source code. To do this navigate to the "Code" button on the navbar then select your branch name then navigate through the code via blogs->->->images. From here you can select "Add file" and "Upload files". The image should be referenced in the README.md by its file name.
- When changes or additions have been made make sure to commit those changes and update the branch with an appropriate commit message to reflect the changes or additions.
Once you believe the blog is in a ready state. On the right hand side of the PR you can add the label "Blog Editor Review Requested". This will notify us that your blog is ready for a review. From here someone from our team will read over the blog and suggest changes to clarify, correct, or align with styling guidelines. From here you can incorporate the suggest feedback either by making the changes manually then resolving the comment threads or committing the changes directly from the comment. After 2-3 round of review the blog will be ready for publishing and someone from the team will push it to the live site!
Every time you make a commit to update your blog, a series of checks will run to verify that tags, metadata, markdown formatting, and keywords are all correct or valid.
In the event that one of these checks fails the PR will have an X beside it instead of a check mark. You can go to the conversation tab on the PR and scroll to the bottom of the page to see these checks. Then you can select which one failed and see why so you can make any appropriate changes. In the event you cannot fix or don't know how to fix one of these linting errors you can reach out to someone on our team, and we will provide assistance. Note that all linting checks must pass for a blog to get published.
It's important that you can see what your blog will look like before it's live. To do this you can look in the same place as the linting checks are and there will be a link that says docs/readthedocs.com:advanced-micro-devices-rocm-blogs and clicking on it will lead to a render of the blog site. From the blog site you can look in recent blogs and select yours to view it.
ROCm Blogs allows external contributors such as yourself to share technologies and innovations related to AMD providing easily digestible and accessible content to all types of developers and AMD users.
If you ever find you are having problems or need assistance creating a blog, please reach out to someone on our team and we will be more than happy to walk you through the process.
We look forward to seeing your blogs!