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.
Sign up for Github
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 SharePOoint 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.
Create Your Markdown
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.
Convert Word Documents
If you have your content in a Word document, you can use one of several Word to markdown conversion tools:
Convert from an existing blog post
If you're starting with an existing blog post, then you may be able to convert the HTML from the post to markdown.
Write from scratch
If you're writing new content from scratch, you can choose whichever editor you like. The importent 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.
NOTE: Many of the tools mentioned above are developed by third parties, thus we cannot vouch for them. Let us know what issues or succcesses you have in the Issues.
Add to the Repository
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.
Navigate to the Appropriate Location
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. For example, you might want to add your content to the docs/making-decisions folder if it's an article about how to decide whether to use Teams Site vs. Communication Site: Which one should I choose? Don't stress too much about this: the contributions we get will drive rerstructuring over time.
Create the New File
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.
Name the file
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.
Edit the file
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 drectory 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
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
Save the file
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.
Push the Commit new file button and your content will be on its way into the repo. However, 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.