Edit on GitHub
Writing a Blog Post
Been to a conference recently? Worked on something cool? Got something else Mattermost-related you want to post about? Writing a blog post is a great way to share your experience with the community.
Blog posts can cover a wide range of topics, such as:
- Addressing a customer-facing problem
- Describing an experience with Mattermost/your Mattermost implementation
- Sharing information about cool tech
- Sharing feedback on an interesting talk or conference
- Part of a Hackathon project
- A Help Wanted ticket
- A knowledge-share and call for feedback/community engagement
- A discussion of a specific problem or improvement that you worked on
- A breakdown of a new process or technology you’re using
Once you’ve got the topic in mind - what it’s about, what you want to achieve with the post, and what the next steps are - it’s sometimes helpful to start writing the conclusion and expand to your jumping off point to introduce your topic/idea/discovery draws.
Make a note of your intended audience, so you can decide whether to use very technical terms/jargon, or spend time unpacking terminology.
Structuring Your Blog Post
These are some ideas of the parts of a blog post. They’re not mandatory and not all blog posts will include every aspect. What works for some posts won’t work for others.
- Introduction/Overview: An opening paragraph detailing the goal of the post and the technologies/processes that were used. For example: “Monitoring is an essential part of our organization. When we started, we were using “x” which gave us insight into “y”. With our growth as a company, we need more insights into areas that “x” can’t handle, so we decided to switch to “a” and “b””.
- Problem/Solution/Situation: Detail the problem or scenario that sparked the blog post. For example, “Our monitoring tools weren’t giving us the insight we needed, and were costing a lot of money. We decided to try solve this by using multiple tools that could be used or on standby as needed. This saves money.”
- Environment: Plugins, software, specific configurations/services used.
- Steps: The process followed to get from conception to implementation, for example, how the monitoring was configured initially, and the new configuration. Include code samples and/or screenshots. How long it took to build a database/history. What steps were taken to create a good alert system.
- Samples: Code samples are often useful, as are screenshots/animated GIFs if a complex process is being demonstrated.
- Benefits: The benefits of the exercise or process of the blog post - man-hours saved, budget target achieved, lower overheads, etc.
- Conclusion: Whether the exercise or process has long-term potential, whether it’s still in place, or whether it was a failure.
Some popular blogs that are worth reading include:
The /site/content/blog/ folder also has some good examples.
Writing Your Blog Post
The steps below outline the process involved in creating the blog post file from a cloned repo, and then submitting the PR.
- Clone https://github.com/mattermost/mattermost-developer-documentation.
- Create a new .md file in the /site/content/blog/ folder.
YYYY-MM-DD-<your-blog-post-title>.md as the filename.
Paste this template into your file
title: <user readable title of your blog post, e.g. My Blog Post>
slug: <URL name of your blog post, e.g. my-blog-post>
author: <FirstName LastName>
github: <your GitHub username>
community: <your community.mattermost.com username>
<intro to blog post>
#### <some heading>
#### <another heading>
<some more content>
Write your blog post.
(Optional) If you wrote the blog post with someone else, you can also add a second author by adding
community_2 to the front matter.
Submit a pull request to https://github.com/mattermost/mattermost-developer-documentation and assign two dev reviews and an editor review from @amyblais or @justinegeffen.
Once merged it should show up on developers.mattermost.com/blog within 10-15 minutes. When it shows up, post about it in the Developers channel on community.mattermost.com.