What is Markdown?
Who uses Markdown?
Why developers like Markdown?
Here are some stack decisions, common use cases and reviews by companies and developers who chose Markdown in their tech stack.
We just launched the Segment Config API (try it out for yourself here) — a set of public REST APIs that enable you to manage your Segment configuration. A public API is only as good as its #documentation. For the API reference doc we are using Postman.
Postman is an “API development environment”. You download the desktop app, and build API requests by URL and payload. Over time you can build up a set of requests and organize them into a “Postman Collection”. You can generalize a collection with “collection variables”. This allows you to parameterize things like
workspace_name so a user can fill their own values in before making an API call. This makes it possible to use Postman for one-off API tasks instead of writing code.
Then you can add Markdown content to the entire collection, a folder of related methods, and/or every API method to explain how the APIs work. You can publish a collection and easily share it with a URL.
This turns Postman from a personal #API utility to full-blown public interactive API documentation. The result is a great looking web page with all the API calls, docs and sample requests and responses in one place. Check out the results here.
Postman’s powers don’t end here. You can automate Postman with “test scripts” and have it periodically run a collection scripts as “monitors”. We now have #QA around all the APIs in public docs to make sure they are always correct
Along the way we tried other techniques for documenting APIs like ReadMe.io or Swagger UI. These required a lot of effort to customize.
Writing and maintaining a Postman collection takes some work, but the resulting documentation site, interactivity and API testing tools are well worth it.
For Stack Decisions I needed to add Markdown in the decision composer to give our users access to some general styling when writing their decisions. We used React & GraphQL on the #Frontend and Ruby & GraphQL on the backend.
Instead of using Showdown or another tool, We decided to parse the Markdown on the backend so we had more control over what we wanted to render in Markdown because we didn't want to enable all Markdown options, we also wanted to limit any malicious code or images to be embedded into the decisions and Markdown was a fairly large to import into our component so it was going to add a lot of kilobytes that we didn't need.
We also needed to style how the markdown looked, we are currently using Glamorous so I used that but we are planning to update this to Emotion at some stage as it has a fairly easy upgrade path rather than switching over to styled-components or one of the other cssInJs alternatives.
Also we used React-Mentions for tagging tools and topics in the decisions. Typing
@ will let you tag a tool, and typing
# will allow you to tag a topic.
The Markdown options that we chose to support are tags:
If there are anymore tags you'd love to see added in the composer leave me a comment below and we will look into adding them.
We've been incredibly happy with the choice of Markdown as the composition language for Zulip:
- Everyone can write it, since it's just like email and many other products use it.
- It has a WYSIWYG type experience, so we don't feel the need to integrate a fancy editor like Quill.
- Rendering to HTML is fast, easy to do automated tests for, and easy to debug.
We have had to customize our Markdown implementation somewhat for the chat context, because we don't have the guarantee that content is not split across multiple messages (a good example is that you don't want the "automatically change numbered lists to start at 1" feature in default markdown; you want to restrict that to numbered lists where all the numbers are 1, for example) .
So I am a huge fan of JIRA like #massive I used it for many many years, and really loved it, used it personally and at work. I would suggest every new workplace that I worked at to switch to JIRA instead of what I was using.
When I started at #StackShare we were using a Trello #Kanban board and I was so shocked at how easy the workflow was to follow, create new tasks and get tasks QA'd and deployed. What was so great about this was it didn't come with all the complexity of JIRA. Like setting up a project, user rules etc. You are able to hit the ground running with Trello and get tasks started right away without being overwhelmed with the complexity of options in JIRA
With a few TrelloPowerUps we were easily able to add GitHub integration and storyPoints to our cards and thats all we needed to get a really nice agile workflow going.
I'm not saying that JIRA is not useful, I can see larger companies being able to use the JIRA features and have the time to go through all the complex setup to get a really good workflow going. But for smaller #Startups that want to hit the ground running Trello for me is the way to go.
In saying that what I would love Trello to implement is to allow me to create custom fields. Right now we just have a
Description field. So I am adding
User Stories &
How To Test in the Markdown of the
Description if I could have these as custom fields then my #Agile workflow would be complete.
More than year ago I was looking for the best editor of Angular 2 application and I've tried Visual Studio Code and Atom. Atom had performance issues that put me off completely to use it again. Visual Studio Code became my main editor #Typescript files (and partly editor of #Java files). I'm happy with Visual Studio Code and I've never look back on Atom. There wasn't any reason to try Atom again, because Visual Studio Code fulfills my requirements very well. I use it for editing of TypeScript, #HTML, #Sass, JSON, Docker and Markdown.
I needed to make stack decisions accept a subset of Markdown, similarly to sites like Reddit or Stack Overflow.
Problem solved! #StackDecisionsLaunch