Review, Start Here

This guide is meant for the review team on the Tanzu Developer Center. When content is submitted, this process will walk you through all essential activities to ensure content is a good fit for the Tanzu Developer Center, that published content has a similar look and feel throughout, and that content is promoted on social media.

There are two primary methods for submitting content to the Tanzu Developer Center: via a GitHub pull request, or via a Google Doc. The review process for each of these will have many similarities; however, the Google Docs submission method requires more collaboration and additional process on behalf of the reviewer since they will still need to open the pull request, and do all of the GitHub activities in addition to the review processes.

This process is provided on the public Wiki in the spirit of openness and collaboration.

Contributions made via GitHub

Conversations between Reviewer and Author -- In general, for these types of contributions, conversations with the author should take place in the open via GitHub tools. Typically this means the Conversations tab within the pull request.

• Review if the content is a good fit for the Tanzu Developer Center.

  • Check the Is my content a good fit for the Tanzu Developer Center. It is okay to offer feedback on how to modify the content so that it would be a good fit. It is also okay to suggest other content targets where the content might be a better fit.

• There is a GitHub issue created for the piece of content, and that card has been added to the content backlog project appropriately.

  • We like to track the content being released on the Tanzu Developer Center for many reasons, including our commitment to openness in the development process, our need to openly review content, and for the purposes of future content planning. Please ensure that a card has been added, has relevant tags, placed in the proper project, has assignees as necessary, the issue is attached to the pull request, etc.

• Ensure with the author that the content has been reviewed for technical accuracy.

  • This is necessary even if the author themselves is the topic's subject matter expert. For example, with how-to guides, it is common for "simple" steps to be assumed and skipped, while readers who are trying to learn the topic may not know that is a necessary step.

• Ensure with the author that the content has been through copy editing.

  • Copy Editing is a formal process and is different from the author's colleagues reviewing the content. There are a few Copy Editors on staff at VMware. If you need help finding a copy editor, ask another Tanzu Developer Center Admin. For content submitted via GitHub, this will require the author to move or copy their content to a sharable format where changes can be tracked, typically a Google Doc.

• If applicable, ensure with the author that the content has been through Legal review.

  • This is not applicable for most content in the Tanzu Developer Center. Typically product announcements, particularly those with forward looking statements, will need this kind of review.

• Review fit with the Tanzu Developer Center Style Guide and the VMware Style Guide.

  • We want all content on the Tanzu Developer Center to have a similar look and feel. Adhering to our style guides is a good way to do that, while not being too heavy handed on the actual content.

• Ensure the front matter is filled out correctly and completely.

  • For most types of content, the required fields will be title, date, description, topics, tags, and team. If you think additional information is needed, collaborate with the author.

• If applicable, review additions to custom_dict.txt.

  • Things that typically belong in custom_dict.txt are typically proper names of people, tools, companies and the like. Also established or well-known abbreviations or acronyms. Things that typically don't belong are library names, function names, API methods, and the like. For these items, in accordance with the Style Guide, they should be wrapped using in-line code formatting, or in a code block. In either case the spell checker will ignore these.

• Ensure with the author they have reviewed the staging site for correctness. The reviewer should review this too.

  • The final test when creating a pull request is for Netlify to create a staging site. Ensure with the author that everything looks as they intended. As the reviewer, make sure that nothing looks out of place or obviously incorrect.

• If applicable, review any new Team pages.

  • If this is the author's first submission to the Tanzu Developer Center, they should create a new Team page. The process for creating one can be found here. Ensure that all necessary fields have been filled out correctly and completely. Typically this includes name, description (the author's role or position), photo (linked properly), skills (optional), location (City, State/Provenance/Country), and links to any social media the author would like to promote.

• If applicable, the author has provided copy for Social Media distribution.

  • If the author would like to have the opportunity to have their content push through the Tanzu Social Media team accounts, they need to provide some sample copy to the Social Media team. They can do this directly through their submission form, or by providing copy to the reviewer. In the latter case the reviewer would fill out the same form on behalf of the author.

Contributions made via Google Docs

Conversations between Reviewer and Author -- For contributions made via Google Docs, the Form used to submit content should ensure that all steps which the author is responsible for are completed. To the extent that a conversation does need to take place, there isn't an ideal method which allows for easy unobtrusive conversation which is also trackable and done in the open. As for now, Direct Messages in Slack are fine, but the portions of the conversation which are of consequence and related to the below checklist should be copied and pasted by the reviewer into the GitHub pull request conversation, once that stage is reached.

• Review if the content is a good fit for the Tanzu Developer Center.

  • Check the Is my content a good fit for the Tanzu Developer Center. It is okay to offer feedback on how to modify the content so that it would be a good fit. It is also okay to suggest other content targets where the content might be a better fit.

• Ensure all parts of the Google Form have been filled out correctly and completely.

  • The Google Form will ask the submitter if they have completed various tasks, asks them to fill in front matter items such as the description, topics, tags, author, etc. If it's their first time submitting to the Tanzu Developer Center, it will also ask them to fill out relevant sections of the team page. Ensure these are all filled out as expected.

• There is a GitHub issue created for the piece of content, and that card has been added to the content backlog project appropriately.

  • We like to track the content being released on the Tanzu Developer Center for many reasons, including our commitment to openness in the development process, our need to openly review content, and for the purposes of future content planning. Please ensure that a card has been added, has relevant tags, placed in the proper project, has assignees as necessary, the issue is attached to the pull request, etc.

• Ensure with the author that the content has been reviewed for technical accuracy.

  • This is necessary even if the author themselves is the topic's subject matter expert. For example, with how-to guides, it is common for "simple" steps to be assumed and skipped, while readers who are trying to learn the topic may not know that is a necessary step.

• Ensure with the author that the content has been through copy editing.

  • Copy Editing is a formal process and is different from the author's colleagues reviewing the content. There are a few Copy Editors on staff at VMware. If you need help finding a copy editor, ask another Tanzu Developer Center Admin.

• If applicable, ensure with the author that the content has been through Legal review.

  • This is not applicable for most content in the Tanzu Developer Center. Typically product announcements, particularly those with forward looking statements, will need this kind of review.

• Review fit with the Tanzu Developer Center Style Guide and the VMware Style Guide.

  • We want all content on the Tanzu Developer Center to have a similar look and feel. Adhering to our style guides is a good way to do that, while not being too heavy handed on the actual content.

• Open a new local working branch of the tanzu-dev-portal repository.

  • To do this, first make sure that you are currently working on the main branch and that branch is up to date: git checkout main && git pull. Next create a new branch and check it out: git checkout -b $BRANCH_NAME.

• Convert the Google Doc to a markdown file and save to your local branch.

  • At this point, all edits to the document should be completed. Google Docs tools like Docs to markdown work reasonably well; however, certain formatting like internal anchor links and tables seem to confuse it. To create a starter template in the proper location, see that section of the contribution guide.

• Ensure the front matter is filled out correctly and completely.

  • For most types of content, the required fields will be title, date, description, topics, tags, and team. Most of these items should have been submitted as part of the Google Form submission.

• Run local tests.

  • This step entails running the automated tests locally, as well as generating a local deployment preview. For more information on running local test, see that section of the Contribution Guide.

• If applicable, make additions to custom_dict.txt.

  • Things that typically belong in custom_dict.txt are typically proper names of people, tools, companies and the like. Also established or well-known abbreviations or acronyms. Things that typically don't belong are library names, function names, API methods, and the like. For these items, in accordance with the Style Guide, they should be wrapped using in-line code formatting, or in a code block. In either case the spell checker will ignore these.

• If applicable, create any new Team pages.

  • If this is the author's first submission to the Tanzu Developer Center, they should create a new Team page. The process for creating one can be found here. Ensure that all necessary fields have been filled out correctly and completely. Typically this includes name, description (the author's role or position), photo (linked properly), skills (optional), location (City, State/Provenance/Country), and links to any social media the author would like to promote.

• Open the pull request.

  • Here you will need to git add and files which were changed and part of this update. Then git commit -m "$COMMIT_MESSAGE". And finally git push -u origin $BRANCH_NAME. From here, head to the tanzu-dev-portal repo. There should be a button to "Compare and Pull Request". Click that. Fill in the title and description then click "Create pull request". If the local tests ran properly, then all tests should pass here.

• Send the staging link to the author to review. The reviewer should review this too.

  • The final test when creating a pull request is for Netlify to create a staging site. Ensure with the author that everything looks as they intended. As the reviewer, make sure that nothing looks out of place or obviously incorrect. There may be some additional changes requested at this time. Repeat making changes, committing, and pushing changes to your branch as done previously until the content is ready to be released.

• Get the final 👍 from the author to push the content public.

  • It's good to make sure the author is comfortable and ready for you to push the content live. They may want to start promoting it as soon as its live. Or the content may be sensitive and needs to wait for a certain date or time.

• If applicable, send the author the form for the Social Media Request form, or submit it on their behalf.

  • If the author would like to have the opportunity to have their content push through the Tanzu Social Media team accounts, they need to provide some sample copy to the Social Media team. They can do this directly through their submission form, or by providing copy to the reviewer. In the latter case the reviewer would fill out the same form on behalf of the author.