Publishing Guidelines and Examples

December 17, 2015

Report Abuse
This collection goes over a set of guidelines and steps for publishing experiments to the gallery, and includes examples of well-documented content.
The Cortana Analytics Suite is targeted towards data scientists, both new and experienced. The Gallery serves as a forum where people can publish and share their solutions, and by doing so teach others how to use the tools in the Cortana Analytics Suite. This guide was created by a Microsoft Employee. This guide covers: 1. What to publish to the gallery 2. Audience and hints 3. Publishing Steps (for Azure Machine Learning Experiments) 4. Post-publishing 5. Including images in documentation 6. Markdown **1.What to publish to the gallery** ================ These would make a great contribution to the Cortana Analytics Gallery: - New content that illustrates and explains the tools in the Cortana Analytics Suite - Experiments that can serve as reusable solutions We are seeking to create an open community where people can share their own work and find solutions that others have made, helping them to build data science solutions with the Cortana Analytics Suite. **2.Audience and hints** ================ Keep in mind these guidelines while writing documentation: - It's okay to assume the reader has some prior data science experience. However, simplify language and explain in detail where possible. - You should NOT assume that the reader knows how to use the Cortana Analytics Suite. Provide enough information for other users to be able to build the same thing themselves with step-by-step explanations. - Screenshots of data and the experiment graph and other visuals are very helpful in getting a reader to understand how to interpret and use your content. See the image hosting section for details on how you can include images in your documentation. - If you are a Microsoft Employee, include the text "Created by a Microsoft Employee" in the summary or description of your documentation. - If your dataset is part of your experiment and not being imported through a reader module, it's part of your experiment and gets published to the Gallery with your experiment. For this reason ensure that the dataset you're publishing with the experiment has the appropriate licensing terms that allow sharing and downloading by anyone. **3.Publishing steps ( Azure Machine Learning Experiments)** ================ When you are ready to publish to the gallery, follow the five steps below. ![](https://raw.githubusercontent.com/raghoshMSFT/gallery-photos/master/gallerypublishing_step1.png) 1. Fill out the title and tags fields. Keep them descriptive, highlighting the techniques used or the real-world problem being solved. Example: “Binary Classification: Twitter sentiment analysis” 2. Write a summary of what your content covers. Briefly describe the problem being solved and how you approached it. **Legal Requirement for Microsoft Employees:** *Include the text “Created by a Microsoft Employee” in your summary, or elsewhere in the description.* 3. Use the detailed description box to step through the different parts of your experiment. You can use Markdown to format it as needed. Click the Preview icon to see approximately how it will look when published. The examples in this collection show what to include and how you might organize the information. **Tip:** *The box provided for Markdown editing and preview box is quite small. We recommend that you write your documentation in a Markdown editor and paste the completed document into the text box. After you have finished publishing your experiment, you will be able to use the standard web-based tools in Markdown for editing and preview to make necessary tweaks and corrections.* ![](https://raw.githubusercontent.com/raghoshMSFT/gallery-photos/master/gallerypublishing_step2.png) 4. Upload a thumbnail image for your gallery item. This will appear at the top of the item page and in the item tile when browsing the gallery. You can choose an image from your computer or select one of the stock images. ![](https://raw.githubusercontent.com/raghoshMSFT/gallery-photos/master/gallerypublishing_step3.png) 5. Choose whether to publish your content publicly, or have it only accessible to people with the link. **Tip:** *If you want to make sure your documentation looks right before releasing it publicly, you can publish it as unlisted first, and then switch it to Public from the item page. Once an item is made public, it cannot be switch back to the unlisted state.* ![publishing done](https://raw.githubusercontent.com/raghoshMSFT/gallery-photos/master/gallerypublishing_done.png) All done! You can now view your experiment in the gallery and share the link with others. If you have published it publicly, your experiment will show up in browse and search results in the gallery. You can also make edits to your documentation on the item page any time you are logged in to your account. **Tip:** *To make changes to the experiment you have published, go back to the experiment in Azure ML Studio, make changes, and publish again. By default, it will update your existing published content and not create a new one.* **4.Post-publishing** ================ Now that you have published your work to the gallery, others can download it and use it to learn or for their own projects. ## Subscribe to comments People often leave comments on gallery items to ask questions or discuss methodology. To make sure you get notified when people make comments on items you have published, go to the bottom of the item page and create or log into a Disqus account. You will then be able to click “Subscribe” to be notified by email when there is a new comment on that item. ![](https://raw.githubusercontent.com/raghoshMSFT/gallery-photos/master/gallerypublishing_comments.png) ## Sharing your work We highly encourage you to share your published content via blogs, LinkedIn, or other social media. This is a great way to build up a body of work that you can show off and get feedback or comments on. **5.Including images in documentation** ================ Authors are highly encouraged to include screenshots of their experiment and other visuals in the documentation for an experiment. To do this, you will need to host the images you wish to include on a site like GitHub, and then link to the image from within the markdown for your documentation. Instructions for GitHub image hosting can be found [here](https://help.github.com/articles/adding-images-to-wikis/#linking-to-images-in-a-repository). **6.Markdown** ================ A guide to basic markdown syntax can be found [here.](https://help.github.com/articles/markdown-basics/) **Note:** *We do not support GitHub Flavored Markdown or other variations of Markdown.* If you prefer to write up your documentation in a markdown editor and copy it in when publishing, we recommend [Markdown pad](http://www.markdownpad.com/).