{"action":"created","comment":{"url":"https://api.github.com/repos/openshift/openshift-docs/pulls/comments/83029850","pull_request_review_id":3896629,"id":83029850,"diff_hunk":"@@ -268,6 +271,84 @@ another topic, see the following usage:\n \n http://asciidoctor.org/docs/user-manual/#include-multiple\n \n+== Writing concepts\n+Concepts should support the things that users want to do and should not include","path":"contributing_to_docs/doc_guidelines.adoc","position":24,"original_position":24,"commit_id":"3b6fdef3b7b16b05be89cb9cccd291a428149a19","original_commit_id":"3b6fdef3b7b16b05be89cb9cccd291a428149a19","user":{"login":"aheslin","id":21225686,"avatar_url":"https://avatars.githubusercontent.com/u/21225686?v=3","gravatar_id":"","url":"https://api.github.com/users/aheslin","html_url":"https://github.com/aheslin","followers_url":"https://api.github.com/users/aheslin/followers","following_url":"https://api.github.com/users/aheslin/following{/other_user}","gists_url":"https://api.github.com/users/aheslin/gists{/gist_id}","starred_url":"https://api.github.com/users/aheslin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aheslin/subscriptions","organizations_url":"https://api.github.com/users/aheslin/orgs","repos_url":"https://api.github.com/users/aheslin/repos","events_url":"https://api.github.com/users/aheslin/events{/privacy}","received_events_url":"https://api.github.com/users/aheslin/received_events","type":"User","site_admin":false},"body":"I agree with both of you and I'll work on getting an example that's more applicable to OpenShift.","created_at":"2016-10-12T15:20:54Z","updated_at":"2016-10-12T15:20:55Z","html_url":"https://github.com/openshift/openshift-docs/pull/2990#discussion_r83029850","pull_request_url":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990","_links":{"self":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/comments/83029850"},"html":{"href":"https://github.com/openshift/openshift-docs/pull/2990#discussion_r83029850"},"pull_request":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990"}}},"pull_request":{"url":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990","id":87971376,"html_url":"https://github.com/openshift/openshift-docs/pull/2990","diff_url":"https://github.com/openshift/openshift-docs/pull/2990.diff","patch_url":"https://github.com/openshift/openshift-docs/pull/2990.patch","issue_url":"https://api.github.com/repos/openshift/openshift-docs/issues/2990","number":2990,"state":"open","locked":false,"title":"[WIP]Additions and clarifications to doc guidelines","user":{"login":"ahardin-rh","id":16197393,"avatar_url":"https://avatars.githubusercontent.com/u/16197393?v=3","gravatar_id":"","url":"https://api.github.com/users/ahardin-rh","html_url":"https://github.com/ahardin-rh","followers_url":"https://api.github.com/users/ahardin-rh/followers","following_url":"https://api.github.com/users/ahardin-rh/following{/other_user}","gists_url":"https://api.github.com/users/ahardin-rh/gists{/gist_id}","starred_url":"https://api.github.com/users/ahardin-rh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ahardin-rh/subscriptions","organizations_url":"https://api.github.com/users/ahardin-rh/orgs","repos_url":"https://api.github.com/users/ahardin-rh/repos","events_url":"https://api.github.com/users/ahardin-rh/events{/privacy}","received_events_url":"https://api.github.com/users/ahardin-rh/received_events","type":"User","site_admin":false},"body":"@adellape @aheslin @bfallonf @tpoitras @vikram-redhat Here is my first pass at the revised doc guidelines. I really want to remove the guess work from the markdown we use. We were running into a lot of inconsistencies and I think that simplifying things will help. The biggest proposed change in that regard is changing the formatting for environment variables to back-ticks. Other product groups seem to use that convention as well.  Per a conversation with @aheslin I also added in guidelines on writing tasks vs concepts vs user goals, and a few other bits of guidance that I think were missing. Please share your thoughts and let me know if I missed anything.","created_at":"2016-10-04T20:48:44Z","updated_at":"2016-10-12T15:20:55Z","closed_at":null,"merged_at":null,"merge_commit_sha":"ba2f5b13328963a6c1866aaedcccd9551ed1a257","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990/commits","review_comments_url":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990/comments","review_comment_url":"https://api.github.com/repos/openshift/openshift-docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/openshift/openshift-docs/issues/2990/comments","statuses_url":"https://api.github.com/repos/openshift/openshift-docs/statuses/3b6fdef3b7b16b05be89cb9cccd291a428149a19","head":{"label":"ahardin-rh:docs-guidelines","ref":"docs-guidelines","sha":"3b6fdef3b7b16b05be89cb9cccd291a428149a19","user":{"login":"ahardin-rh","id":16197393,"avatar_url":"https://avatars.githubusercontent.com/u/16197393?v=3","gravatar_id":"","url":"https://api.github.com/users/ahardin-rh","html_url":"https://github.com/ahardin-rh","followers_url":"https://api.github.com/users/ahardin-rh/followers","following_url":"https://api.github.com/users/ahardin-rh/following{/other_user}","gists_url":"https://api.github.com/users/ahardin-rh/gists{/gist_id}","starred_url":"https://api.github.com/users/ahardin-rh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ahardin-rh/subscriptions","organizations_url":"https://api.github.com/users/ahardin-rh/orgs","repos_url":"https://api.github.com/users/ahardin-rh/repos","events_url":"https://api.github.com/users/ahardin-rh/events{/privacy}","received_events_url":"https://api.github.com/users/ahardin-rh/received_events","type":"User","site_admin":false},"repo":{"id":47579606,"name":"openshift-docs","full_name":"ahardin-rh/openshift-docs","owner":{"login":"ahardin-rh","id":16197393,"avatar_url":"https://avatars.githubusercontent.com/u/16197393?v=3","gravatar_id":"","url":"https://api.github.com/users/ahardin-rh","html_url":"https://github.com/ahardin-rh","followers_url":"https://api.github.com/users/ahardin-rh/followers","following_url":"https://api.github.com/users/ahardin-rh/following{/other_user}","gists_url":"https://api.github.com/users/ahardin-rh/gists{/gist_id}","starred_url":"https://api.github.com/users/ahardin-rh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ahardin-rh/subscriptions","organizations_url":"https://api.github.com/users/ahardin-rh/orgs","repos_url":"https://api.github.com/users/ahardin-rh/repos","events_url":"https://api.github.com/users/ahardin-rh/events{/privacy}","received_events_url":"https://api.github.com/users/ahardin-rh/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ahardin-rh/openshift-docs","description":"OpenShift Documentation","fork":true,"url":"https://api.github.com/repos/ahardin-rh/openshift-docs","forks_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/forks","keys_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/teams","hooks_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/hooks","issue_events_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/issues/events{/number}","events_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/events","assignees_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/assignees{/user}","branches_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/branches{/branch}","tags_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/tags","blobs_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/languages","stargazers_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/stargazers","contributors_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/contributors","subscribers_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/subscribers","subscription_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/subscription","commits_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/contents/{+path}","compare_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/merges","archive_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/downloads","issues_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/issues{/number}","pulls_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/labels{/name}","releases_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/releases{/id}","deployments_url":"https://api.github.com/repos/ahardin-rh/openshift-docs/deployments","created_at":"2015-12-07T21:14:47Z","updated_at":"2016-01-11T14:22:03Z","pushed_at":"2016-10-11T20:35:45Z","git_url":"git://github.com/ahardin-rh/openshift-docs.git","ssh_url":"git@github.com:ahardin-rh/openshift-docs.git","clone_url":"https://github.com/ahardin-rh/openshift-docs.git","svn_url":"https://github.com/ahardin-rh/openshift-docs","homepage":null,"size":21497,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"openshift:master","ref":"master","sha":"848ffa4061afde2e1c18b22a74ede413a5c4c51e","user":{"login":"openshift","id":792337,"avatar_url":"https://avatars.githubusercontent.com/u/792337?v=3","gravatar_id":"","url":"https://api.github.com/users/openshift","html_url":"https://github.com/openshift","followers_url":"https://api.github.com/users/openshift/followers","following_url":"https://api.github.com/users/openshift/following{/other_user}","gists_url":"https://api.github.com/users/openshift/gists{/gist_id}","starred_url":"https://api.github.com/users/openshift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openshift/subscriptions","organizations_url":"https://api.github.com/users/openshift/orgs","repos_url":"https://api.github.com/users/openshift/repos","events_url":"https://api.github.com/users/openshift/events{/privacy}","received_events_url":"https://api.github.com/users/openshift/received_events","type":"Organization","site_admin":false},"repo":{"id":21740844,"name":"openshift-docs","full_name":"openshift/openshift-docs","owner":{"login":"openshift","id":792337,"avatar_url":"https://avatars.githubusercontent.com/u/792337?v=3","gravatar_id":"","url":"https://api.github.com/users/openshift","html_url":"https://github.com/openshift","followers_url":"https://api.github.com/users/openshift/followers","following_url":"https://api.github.com/users/openshift/following{/other_user}","gists_url":"https://api.github.com/users/openshift/gists{/gist_id}","starred_url":"https://api.github.com/users/openshift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openshift/subscriptions","organizations_url":"https://api.github.com/users/openshift/orgs","repos_url":"https://api.github.com/users/openshift/repos","events_url":"https://api.github.com/users/openshift/events{/privacy}","received_events_url":"https://api.github.com/users/openshift/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/openshift/openshift-docs","description":"OpenShift Documentation","fork":false,"url":"https://api.github.com/repos/openshift/openshift-docs","forks_url":"https://api.github.com/repos/openshift/openshift-docs/forks","keys_url":"https://api.github.com/repos/openshift/openshift-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/openshift/openshift-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/openshift/openshift-docs/teams","hooks_url":"https://api.github.com/repos/openshift/openshift-docs/hooks","issue_events_url":"https://api.github.com/repos/openshift/openshift-docs/issues/events{/number}","events_url":"https://api.github.com/repos/openshift/openshift-docs/events","assignees_url":"https://api.github.com/repos/openshift/openshift-docs/assignees{/user}","branches_url":"https://api.github.com/repos/openshift/openshift-docs/branches{/branch}","tags_url":"https://api.github.com/repos/openshift/openshift-docs/tags","blobs_url":"https://api.github.com/repos/openshift/openshift-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/openshift/openshift-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/openshift/openshift-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/openshift/openshift-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/openshift/openshift-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/openshift/openshift-docs/languages","stargazers_url":"https://api.github.com/repos/openshift/openshift-docs/stargazers","contributors_url":"https://api.github.com/repos/openshift/openshift-docs/contributors","subscribers_url":"https://api.github.com/repos/openshift/openshift-docs/subscribers","subscription_url":"https://api.github.com/repos/openshift/openshift-docs/subscription","commits_url":"https://api.github.com/repos/openshift/openshift-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/openshift/openshift-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/openshift/openshift-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/openshift/openshift-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/openshift/openshift-docs/contents/{+path}","compare_url":"https://api.github.com/repos/openshift/openshift-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/openshift/openshift-docs/merges","archive_url":"https://api.github.com/repos/openshift/openshift-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/openshift/openshift-docs/downloads","issues_url":"https://api.github.com/repos/openshift/openshift-docs/issues{/number}","pulls_url":"https://api.github.com/repos/openshift/openshift-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/openshift/openshift-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/openshift/openshift-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/openshift/openshift-docs/labels{/name}","releases_url":"https://api.github.com/repos/openshift/openshift-docs/releases{/id}","deployments_url":"https://api.github.com/repos/openshift/openshift-docs/deployments","created_at":"2014-07-11T15:14:42Z","updated_at":"2016-10-03T12:47:30Z","pushed_at":"2016-10-12T14:58:11Z","git_url":"git://github.com/openshift/openshift-docs.git","ssh_url":"git@github.com:openshift/openshift-docs.git","clone_url":"https://github.com/openshift/openshift-docs.git","svn_url":"https://github.com/openshift/openshift-docs","homepage":"https://docs.openshift.org/latest/welcome/index.html","size":29251,"stargazers_count":56,"watchers_count":56,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":260,"mirror_url":null,"open_issues_count":211,"forks":260,"open_issues":211,"watchers":56,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990"},"html":{"href":"https://github.com/openshift/openshift-docs/pull/2990"},"issue":{"href":"https://api.github.com/repos/openshift/openshift-docs/issues/2990"},"comments":{"href":"https://api.github.com/repos/openshift/openshift-docs/issues/2990/comments"},"review_comments":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990/comments"},"review_comment":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/openshift/openshift-docs/pulls/2990/commits"},"statuses":{"href":"https://api.github.com/repos/openshift/openshift-docs/statuses/3b6fdef3b7b16b05be89cb9cccd291a428149a19"}}}}
{"actor":{"display_login":"aheslin"}}