@xrdocs Guest Bloggers

Back to @xrdocs How-To

First Steps:

As we’ve already explained in the xrdocs How-To guide/First Steps section,

Request access to the xrdocs/xrdocs-images images repository and set up your author profile by sending an email to the xrdocs-team with the following data:

• Full Name
• Github ID
• Email
• attach a bio photo in jpg/jpeg/png format
• twitter handle (optional)

Quick Recap on types of Users @xrdocs

There are 2 types of users on @xrdocs

• Owners/contributors of the corresponding github repos (app-hosting, telemetry etc.). The documents created by these users on prose.io directly get committed to the github repos (hence the website), when saved.
• Guest Bloggers: Do NOT have write access to repositories. All their documents created on prose.io appear as pull requests on github, and are subject to a peer review by the owners/contributors before merging with the website.

TMEs in the Web Solutions group at Cisco are by default the owners of the internal github repositories that host the XR documentation.

Guest Bloggers

“Guest Blogger” is a generic term we use to define any user that does not have write access to the internal github repository where the documents get stored.

Without going into details of how the github organization (xrdocs) and its repositories (application-hosting, telemetry etc.) are set up, it would be good to understand which repositories a Guest Blogger will be granted access to:

xrdocs/xrdocs-images is the only repository that Guest bloggers will have write access to. Think of this as your image repository in the cloud.

Document Creation Workflow

As a Guest Blogger, document creation is very similar to an owner/contributor workflow, except:

• Create a local copy of your markdown content
• Use prose.io to submit your content for review
• Update github pull request based on reviewer’s comments.
• Create new pull requests using prose.io if the changes required are massive

Commit and Peer review: Important

Let’s take an illustrative example to see how the commit and peer review process may happen in real life.

Create a Local Markdown file

As a guest blogger, I open my markdown content in my markdown editor of choice, let’s say the Atom.io editor.

This is my local markdown file, I’ll use it to keep my content saved and updated.

Submit the content on prose.io

Let’s assume we’re contributing to the application-hosting xrdocs website at https://xrdocs.github.io/application-hosting

Open up prose.io and point to the github-pages repo of the repository:
(Browse to http://prose.io/#xrdocs/application-hosting/tree/gh-pages)

Click on _blogs folder and then on NEW FILE button.

Copy and paste your markdown content into the prose.io window and set a title for your blog:

Set the metadata fields appropriately:

Finally commit/Save the content by clicking the commit button or issuing a Ctrl+S

Done! You’ve submitted a pull request!

Peer Review

A pull request will appear for the gh-pages branch of the application-hosting Repository. Scoot over to the link: https://github.com/xrdocs/application-hosting/pulls and you should see the pull request created.

As an owner/contributor for the Github repo in question, look around, view the commit, view the rendered markdown file:

Click on “Files Changed” to view the diffs

Provide comments just like you do on code:

Provide inline comments!

As the Guest blogger, if there are any updates, edit the pull request in github itself

Use github itself to make edits if needed

If the changes are massive, you can submit a whole new pull request through prose.io and the reviewer can close the original pull request. However, be aware that if you submit a new pull request then your content will have to come from your local copy, prose.io is not going to reflect your earlier commit, because it wasn’t accepted by the reviewer.

If everyone is happy, the reviewer can merge the changes: Confirm merge to integrate the new blog.

The Guest Blog should Appear on the website in about 10-30 seconds.