What is Markdown?
Who uses 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.
I am starting to become a full-stack developer, by choosing and learning .NET Core for API Development, Angular CLI / React for UI Development, MongoDB for database, as it a NoSQL DB and Flutter / React Native for Mobile App Development. Using Postman, Markdown and Visual Studio Code for development.
Our whole DevOps stack consists of the following tools:
- GitHub (incl. GitHub Pages/Markdown for Documentation, GettingStarted and HowTo's) for collaborative review and code management tool
- Respectively Git as revision control system
- SourceTree as Git GUI
- Visual Studio Code as IDE
- CircleCI for continuous integration (automatize development process)
- Prettier / TSLint / ESLint as code linter
- SonarQube as quality gate
- Docker as container management (incl. Docker Compose for multi-container application management)
- VirtualBox for operating system simulation tests
- Kubernetes as cluster management for docker containers
- Heroku for deploying in test environments
- nginx as web server (preferably used as facade server in production environment)
- SSLMate (using OpenSSL) for certificate management
- Amazon EC2 (incl. Amazon S3) for deploying in stage (production-like) and production environments
- PostgreSQL as preferred database system
- Redis as preferred in-memory database/store (great for caching)
The main reason we have chosen Kubernetes over Docker Swarm is related to the following artifacts:
- Key features: Easy and flexible installation, Clear dashboard, Great scaling operations, Monitoring is an integral part, Great load balancing concepts, Monitors the condition and ensures compensation in the event of failure.
- Applications: An application can be deployed using a combination of pods, deployments, and services (or micro-services).
- Functionality: Kubernetes as a complex installation and setup process, but it not as limited as Docker Swarm.
- Monitoring: It supports multiple versions of logging and monitoring when the services are deployed within the cluster (Elasticsearch/Kibana (ELK), Heapster/Grafana, Sysdig cloud integration).
- Scalability: All-in-one framework for distributed systems.
- Other Benefits: Kubernetes is backed by the Cloud Native Computing Foundation (CNCF), huge community among container orchestration tools, it is an open source and modular tool that works with any OS.
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.
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) .