You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 20, 2022. It is now read-only.
- Repetitive use of that —> changed to who
- Wrong tense
- merged should be merge
- Require should be required
- Missing comma
- After using once
- After using when
- The sentence does not make sense —> restructured sentence to make more sense
- Removed hedging
- as simple as possible to simple
- Misplaced the word is
Copy file name to clipboardExpand all lines: repo_docs/FAQ.md
+15-16Lines changed: 15 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -2,27 +2,27 @@
2
2
3
3
## What are best practices for content on GitHub?
4
4
It is best practice to keep each sentence or idea on its own line.
5
-
This is so that anyone that is reviewing a commit can quickly and easily see what changed.
5
+
This is so that anyone who is reviewing a commit can quickly and easily see what changed.
6
6
If you have a giant string of text on a single line then Git just flags that entire line as a 'change'.
7
7
To learn more about this concept, see http://rhodesmill.org/brandon/2012/one-sentence-per-line/.
8
8
9
9
## When will my content go live?
10
10
11
-
When you submit a Pull Request it goes through a validation check and the results are shown on the Pull Request page in GitHub.
12
-
Once the checks are completed, and there are no errors or warnings, and the appropriate sign off has been completed by the product team, a GitHub maintainer will merged the Pull Request into the Master branch on GitHub.
11
+
When you submit a Pull Request, it goes through a validation check and the results are shown on the Pull Request page in GitHub.
12
+
Once the checks are completed, and there are no errors or warnings, and the appropriate sign off has been completed by the product team, a GitHub maintainer will merge the Pull Request into the Master branch on GitHub.
13
13
14
14
A site located at review.docs.microsoft.com shows a mirror of the docs.microsoft.com and pulls from the Master branch.
15
15
Unfortunately the review site requires a Microsoft login at this time.
16
16
This review site provides an opportunity for Microsoft product teams, support, and other internal stakeholders to review any changes before they are pushed to the live site.
17
17
18
18
The next step is for a GitHub maintainer to merge the Master branch into the Live branch.
19
-
Once this is complete the changes in the Pull Request will show up on docs.microsoft.com (docs.microsoft.com pulls its content from the Live branch).
19
+
Once this is complete, the changes in the Pull Request will show up on docs.microsoft.com (docs.microsoft.com pulls its content from the Live branch).
20
20
There is not a set schedule for this to happen but the maintainers are good about doing this fairly quickly.
21
21
22
22
## When does the GitHub content show up in the products with Get-Help?
23
23
24
24
The one source of truth for Office PowerShell cmdlets is the GitHub repository.
25
-
When a product team ships an update or new version they can use the PlatyPS tool to generate XML and add that to the release.
25
+
When a product team ships an update or new version, they can use the PlatyPS tool to generate XML and add that to the release.
26
26
27
27
The XML contains the latest version of the reference content on GitHub.
28
28
Ideally the Online versions will always have the latest content from GitHub and the On Premises products will always have the latest help with Update-Help.
@@ -46,7 +46,7 @@ schema: 2.0.0
46
46
The *external help file* tag is for the docs.microsoft.com infrastructure.
47
47
It can be empty but without it the build will fail.
48
48
49
-
The *applicable* tag is so that when PlatyPS is run to generate the XML that goes in the product it can only pull help content for specific product versions.
49
+
The *applicable* tag is required to pull help content for specific product versions when PlatyPS runs to generate the XML.
50
50
Every applicable tag is located in the [Applicable Tags](https://github.com/MicrosoftDocs/office-docs-powershell/wiki/Applicable-Tags) wiki page.
51
51
These tags have to be added to the docs.microsoft.com infrastructure.
52
52
If you try to include a tag that has not been added then the build will fail.
@@ -79,8 +79,7 @@ Any slight deviation from the format and it won't strip it out and you will see
79
79
80
80
## I can't find the cmdlet I am looking for, what can I do?
81
81
82
-
Finding a cmdlet can sometimes be a challenge.
83
-
This is because you might need to use cmdlets that are in various modules and across multiple products.
82
+
Finding a cmdlet can be a challenge, because you might need to use cmdlets that are in various modules and across multiple products.
84
83
For example, you might need a Windows cmdlet, then an Azure cmdlet, then a SharePoint cmdlet, then an Office 365 cmdlet.
85
84
86
85
The best way to find cmdlets is to use the PowerShell Browser and search.
@@ -91,11 +90,11 @@ You can find the PowerShell Browser here: https://docs.microsoft.com/powershell/
91
90
92
91
You can learn about working with GitHub as a Microsoft employee here: https://docs.opensource.microsoft.com/github/
93
92
94
-
In a nutshell you need to create a GitHub account and link it with your Microsoft account so you can contribute openly.
93
+
In a nutshell, you need to create a GitHub account and link it with your Microsoft account so you can contribute openly.
95
94
96
95
## I made a change and need to get the Pull Request merged ASAP, what can I do?
97
96
98
-
When you submit a Pull Request an email is generated by GitHub and sent to the repository maintainers.
97
+
When you submit a Pull Request, an email is generated by GitHub and sent to the repository maintainers.
99
98
100
99
They try to get to these every day and verify and merge Pull Requests.
101
100
@@ -118,28 +117,28 @@ Also check out Git Kraken https://www.gitkraken.com/ which has a great user inte
118
117
## Why are all the cmdlets for a given product in a single folder in the repo? Wouldn't it be better to put them in buckets?
119
118
GitHub is the single source of truth for Office PowerShell cmdlet reference.
120
119
There is a single reference article per cmdlet.
121
-
There is a folder for each major product area in order to create a basic structure but this isn't require for the system to work.
120
+
There is a folder for each major product area to create a basic structure but this isn't required for the system to work.
122
121
Each article is tagged with appropriate metadata for versioning.
123
-
Keeping things as simple as possible has a number of benefits.
122
+
Keeping things simple has a number of benefits.
124
123
For more about the design of the system, see the FAQ item *"Why is this open source project designed the way it is?"*.
125
124
126
125
127
126
## Why is this open source project designed the way it is?
128
-
The system was designed to be as simple as possible in order to achieve three primary objectives.
127
+
The system design is simple to achieve three primary objectives.
129
128
130
129
1. Increase community engagement.
131
130
132
131
There are many open source projects and every one of them is striving for community involvement.
133
132
We designed the PowerShell reference project to be easily understood in order to increase community ownership and contributions.
134
-
If a person comes to a project and they cannot understand what they can do in 20-30 seconds then they are likely to bounce on to something else.
133
+
If a person comes to a project and they cannot understand what they can do in 20-30 seconds, then they are likely to bounce on to something else.
135
134
The open source PowerShell reference project was designed to break down the barriers to understanding and so someone can ‘flow’ directly into contributions once they have discovered the project.
136
135
A vibrant and active community results in the best reference content that goes directly back into PowerShell Get-Help.
137
136
138
137
1. Central location for content that feeds multiple surfacing mechanisms.
139
138
140
-
The first two places the PowerShell reference content is surfaces is Get-Help in PowerShell itself and the docs.microsoft.com website.
139
+
The first two places the PowerShell reference content surfaces is Get-Help in PowerShell itself and the docs.microsoft.com website.
141
140
In the future the content can also be surfaced in an iOS app, Android app, Windows Universal app, and other mechanisms.
142
-
With a simple, centralized, system for the source of truth, in GitHub, it becomes much easier to surface content using multiple mechanisms since GitHub is not tailored for once specific location, such as Get-Help.
141
+
With a simple, centralized, system for the source of truth, in GitHub, it becomes easier to surface content using multiple mechanisms since GitHub is not tailored for once specific location, such as Get-Help.
143
142
If the GitHub repo focused on one specific site or mechanism then surfacing from other mechanisms could become too complex or could exponentially expound the effort required.
0 commit comments