| title | author | ms.date | ms.reviewer | localization_priority | description | ms.collection |
|---|---|---|---|---|---|---|
Adding content |
sympmarc |
3/3/2020 |
Joanne Hendrickson |
Add content |
SPCommunity |
We'll be following the contribution guidelines from docs.microsoft.com, as we hope the content here ends up there. It even includes a style and voice quick start.
For the full reference, read the Microsoft Writing Style Guide. The style guide is the current iteration of what's been a standard in technical writing for more than 20 years: The Microsoft Manual of Style.
If you don't already have a GitHub account, you won't be able to submit any comments, issues, etc., just like most Web sites and SharePoint itself. If you have an account - you get to skip ahead!
Simply click on the Sign up link at the top right of the page to create your account.
The next step is to gather the content. If you want to contribute something you've already written, it will probably require a bit of conversion. The documentation here is all written in markdown and there is a great markdown cheatsheet you can use if you'd like to write new content or convert something you already have.
If you have your content in a Word document, you can use one of several Word to markdown conversion tools:
If you're starting with an existing blog post, then you may be able to convert the HTML from the post to markdown.
If you're writing new content from scratch, you can choose whichever editor you like. The important thing is to write in markdown format.
- Visual Studio Code is a free editor from Microsoft and is used primarily for code. It also allows you to write markdown with a preview.
- Recommended Extension - Spell Checker - Spell Right - Multilingual, Offline and Lightweight Spell checker for text and markdown files, to help check your files before submission
NOTE: Many of the tools mentioned above are developed by third parties, thus we cannot vouch for them. Let us know what issues or successes you have in the Issues.
If you know how to work with GitHub, you probably don't need this section. You will have forked the repo, edited your fork, and issued a pull request. If that sounds like Greek to you, then here's the simple route to upload a piece of content.
The repo is organized in a set of folders. The structure will undoubtedly change over time, but look for a folder which seems to correspond with the content you want to add. Just add your content to the Community folder.
Near the top of the screen, you'll see a button to Create new file. When you click that button you'll get a new file, which you can give a name and then start editing.
There is only one requirement for the filename, and this is to give it an md extension. This indicates that it is a markdown document. It's just the file extension, like docx for Word docs. As for the name itself, try to use a name which is descriptive, but not too long. For portability, use a name which has dashes to separate the words, like: my-fantastic-article.md.
You can paste in the markdown from the previous steps or type directly into the text box. Note the Preview tab, which allows you to see what the file will look like once you've saved it.
To add images to your article, you'll need to add them to the repository. This is easier if you get more familiar with GitHub and do pull requests, but here is how you can do it through the UI.
We store images in the images directory (folder). Each article should have its own directory underneath images named like the article's title, e.g., "known-folder-move-benefits-for-endusers". You then upload your images into that directory.
The first step is to create the directory. GitHub won't store empty directories, so you need to add a new file into the directory you want to create. Navigate into the images directory, and then click the Create new file button. Type the name of the directory, followed by a forward slash: /.
This will show your name as a directory. Add a file by finishing with index.md. You don't need to use this file, but it'll allow you to create the directory. At the bottom of the screen, click the green Commit new file button.
Now you will be in the directory you just created. Click Upload files to add your images and then Commit changes.
If you can't figure out how to add the images to your article, add a comment to your article with instructions explaining where you would like each one added.
If the content you are contributing is something you are repurposing from your blog or another location, you can add a section at the bottom of your article with information about you and the source. Here's an example:
Principal author: Susan Hanley, MVP
When you are done editing, scroll down to the Commit new file section. Add a title and comments about what you are submitting. This is information which becomes part of the "pull request" - basically you're talking to the people who work on the repo. At this point, you can leave the default option to Commit directly to the master branch. Click the Commit new file button.
On the next page, Comparing changes, click the Create pull request button. In the Write tab edit your pull request details using the template provided. In Category, check off whether it is a content fix, new article, or add a category of your own. Delete the unchecked rows and all instructional text below to the Related Issues header. Under Related Issues you can enter the exact issue number to link this pull request directly to that issue. Delete this section if it does not apply to your pull request. Under What's in this Pull Request? add the description you provided in the previous step for Commit new file. This text was added to the top of this Write tab automatically so cut and paste here instead. Read the Guidance notes for to ensure your pull request is pointed towards the 'master' branch then delete this text. You can select the Preview tab to see how your pull request will appear in email notifications to the administrators. Having a clean pull request makes it easier to approve new content and content changes. Click Create pull request when you have finished all edits.
Your content will have to be accepted before it will be generally available. If there are any questions about what you've submitted, you'll get comments on the pull request. If you provided an email address when you signed up for your GitHub account, you'll get notifications.