Great algorithm descriptions really help developers to understand your algorithms, and help them become successful quickly. Today, we’re happy to announce that we’ve shipped several improvements aimed at helping you write great descriptions, with ready-to-edit sections aimed at helping developers quickly comprehend your algorithm’s purpose and usage.
Algorithm descriptions are based on Markdown and we’ve now shipped a Markdown editor that will let you easily edit your descriptions. The editor is based on CommonMark standard and also includes support for GFM tables.
Algorithm developers who create new public or private algorithms will now notice that we have provided a template that you can fill out, to help other developers understand the why and how of using your algorithm. This template is based on the many different ways we see developers using algorithms on Algorithmia.com, and will touch on the most common questions developers have. If you see anything you think we should include in the template, let us know!
If you need any help with Markdown, you can check out our Markdown Syntax Guide for a full breakdown of what’s supported.
Split-Screen Editing of Markdown
Writing algorithm descriptions typically involves many small iterations of changes. The Markdown editor makes this process easy to make jumping between editing and previewing your description extremely easy. The editor includes a split-screen mode that allows you to see how your description will be rendered as you type and make changes. This has become a favorite way to author algorithm descriptions internally and we’re excited to share it with you!
README.md in Git Repo
Finally, if you prefer to make changes locally using our Git-based development workflow, we are thinking of you too. Algorithm description changes are tracked in your Git repository as changes to a
README.md file. That means you’ll have a full history of any description changes over time. You can now commit and push
README.md changes and your algorithm description will be updated as you might expect.
What about Existing Descriptions?
Algorithm descriptions authored with the old HTML editor continue to render exactly as before. The next time you edit your description, we’ll automatically migrate your old description to Markdown so that you can use the new Markdown editor!
We’re really happy to ship this and looking forward to seeing the improvement of algorithm descriptions across Algorithmia.com! Let us know if you end up having any feedback or run into any issues. We’re always here to help.