Contribution, Drafting Content (GitHub Method)

TDC Contribution Guide - Drafting Initial Content

These processes will walk you through writing your content in markdown, and filling out the Hugo front matter tags.

I would like some tips on drafting Guides, Blogs, and other written content

1. Fill out the front matter block after the initial content has been drafted. This way you will have a better idea of what title, description, and tags to fill in.

2. Utilize the outline provided in the starter template. In the previous step, you created a starter template for your content. These are minimal starters, but best practice is to start with these

3. Start Headings with Level 2 (##). The level 1 Heading will render from the title in the front matter, so subsequent headings should be level 2 or lower. Level 2 headers automatically create anchors, and is included in the right-hand navigation.

4. Utilize the VMware style guide (VMware employees only) and the TDC style guide (VMware employees only). These will help with how to format things like lists, how to format in-line code, code blocks, proper names, etc. And this will make editing easier in later steps.

5. Content should typically be written in second person (the "you" voice). Guides should be written as a 1:1 interaction. Therefore "you/your" is preferred to "we/our" or "me/my".

6. Make sure to include alt text with your images. This is primarily for accessibility reasons. See the Reference page for images for more information).

7. For dates in the future. You can set the front matter date in the future if you want the content to be visible on a specific date. However this will have implications for previewing the content locally (see testing content for more information on this.

8. Check in regularly with the team in the #tanzu-developer-center Slack channel (VMware Employees Only). Ask any questions you may have. Get feedback on your content. Or just confirm your current status.

9. Outline and write or build content as normal. With these tips, you are ready to draft your content. Good luck!

I would like some tips on building Videos

1. Be considerate of the viewers time. Generally the shorter the video, the better. A 2-3 minute video is a great target. A video that runs over 5 minutes is probably too long. Consider if it makes sense to break things up into smaller videos.

2. Get to the point of your video ASAP. Begin by introducing yourself. Summarize the video in a sentence or two, Then jump right in! For VMware videos, always include VMware bumpers before and after the video.

3. Use subtitles. We strongly recommend that you use subtitles in your video so that it is easily enjoyed by all. There are many editing tools that come with the ability to add subtitles. For demos, ensure that the terminal font is clear and readable. Remember that a video may not always be viewed full screen. It’s better to go bigger.

4. The Tanzu Developer Center only hosts already-published videos. Once published (on YouTube for example), you can create a new video template under /content/videos (see how to create a starter template for more information) to provide informative context around the video. For assistance publishing your video, please contact the Social Media team (VMware Employees Only).

I need help with markdown, or adding images, videos, tweets, and callouts to my content

1. See our Shortcodes Reference page. This page links to a markdown reference page, as well as provides content for adding shortcodes to embed various types of content for the Hugo platform.

I need help filling out the front matter

1. For blog posts - Blog posts require a title, date, and author. Here is an example frontmatter section for a blog post:

   ---
   date: 2020-08-11
   description: How does Python look in the cloud-native world of today?
   title: 'Hello Python, My Old Friend: Revisiting Python in a Cloud-Native Climate'
   tags:
   - Kubernetes
   - Python
   - Buildpacks
   team:
   - Brian McClain
   topics:
   - Python
   ---
   

   NOTE: For more information on front matter for Blogs, see the Blogs Front Matter Reference Guide

2. For guides - There are three special front matter fields that can be used in Guides to control how they appear in the sidebar tree navigation. The left side navigation can contain two levels worth of content with each entry capable of containing articles contained underneath. To define what appears where, use the following fields:

   • subsection: defines a Guide as a subsection that can contain one or more guides under it
   • parent: defines the parent subsection for a Guide that should appear under it
   • linkTitle: This is a native, Hugo-supported field to specify a "short" title. This is what will appear in the sidebar tree menu, but the title will still appear on the page (and for SEO purposes).

   Here is an example frontmatter section for a guide:

   ---
   date: '2020-04-16'
   description: Discover how to use pack, a CLI tool that builds container images locally on your developer machine using Cloud Native Buildpacks
   linkTitle: Getting Started with `pack`
   metaTitle: Getting Started with the `pack` CLI
   parent: Cloud Native Buildpacks
   patterns:
   - Deployment
   tags:
   - Buildpacks
   team:
   - Bryan Friedman
   title: Getting Started with the `pack` CLI using Cloud Native Buildpacks
   topics:
   - Containers
   ---
   

   NOTE: For more information on front matter for Guides, see the Guides Front Matter Reference Guide

3. For videos - Make sure to set youtube_id in the front matter to the string that appears after /watch?v= in the video's URL, along with a title, description, and other taxonomy metadata. Here is an example frontmatter section for a video:

   ---
   date: '2020-05-06'
   description: Deploying Kubeapps for your cluster and installing an example application.
   patterns:
   - Deployment
   tags:
   - Kubernetes
   - Kubeapps
   - Helm
   team:
   - Tiffany Jernigan
   title: Getting Started with Kubeapps
   topics:
   - Kubernetes
   youtube_id: 9HsWsoDd1fM
   ---
   

   NOTE: For more information on front matter for Videos, see the Video Front Matter Reference Guide

4. For samples - Along with a title, description, and other taxonomy metadata in the front matter, code sample pages require the full URL to a public GitHub repository in the repo parameter. They also require a boolean value for readme that will determine whether to fetch (at build-time) and render the README content from that repo (true) or to render the content of the page itself instead (false). Here is an example frontmatter section for a code sample:

   ---
   date: '2020-04-21'
   description: Simple Event Driven Microservices with Spring Cloud Stream
   patterns:
   - Eventing
   readme: true
   repo: https://github.com/benwilcock/spring-cloud-stream-demo
   summary:
   - Simple Event Driven Microservices with Spring Cloud Stream
   tags:
   - Spring
   - Microservices
   - Event Streaming
   - Spring Cloud Stream
   team:
   - Ben Wilcock
   title: Spring Cloud Stream Demo
   topics:
   - Spring
   - Messaging and Integration
   - Microservices
   - Event Streaming
   ---