As I was working on the documentation for Khoros's Community Syndication Message List component, I kept thinking about different ways I wanted to use Community Syndication in our Developer Documentation Portal.
For those unfamiliar with Community Syndication, check out this guide and these blogs.
Over the years, folks have asked us why our developer docs are not in Atlas. The simple answer is that some content just doesn't lend itself well to a knowledge base. API reference documentation falls into that category. That said, I wholeheartedly believe in the power of Community, and I wanted a bridge between the Dev Doc Portal and Atlas.
We've got a vibrant and active Developer Discussion forum and I didn't want to disrupt engagement there. I also thought about users coming to the Dev Doc Portal from outside of Atlas -- say following a link to them sent from Khoros Support, Services, or a Customer Success team member. How can we guide those users to the Developer Discussion forum and all of the other great content on Atlas?
The Community Syndication Message List gave me the perfect solution. I'd like to share how easy it was to implement.
Here's what I did
I placed two instances of the component on the developer.khoros.com landing page. Both show messages from the Developer Discussion forum. One displays Latest Topics and the other displays Latest Solutions.
Here's how I did it
I wanted to keep my first implementation simple. I chose to pull content from a single board, but use two separate instances to highlight latest topics vs. solutions.
Here's my content definition in Community Admin for my Latest Solutions message list:
I played with a Card view vs. a List view as well as some other styling formats in Admin to test what my content would look like. Developer Discussion posts aren't image-heavy, so Card View wasn't particularly engaging. I found the List view more readable. I also omitted the View count from the message because, at this time, the view count includes bot traffic. (We've got this issue in our backlog.)
Here's where I landed with my layout configuration.
I placed my Common Script snippet in the <head> of my Dev Doc Portal landing page.
Then, I placed my Component Code in my <body> where I wanted the component to render.
The styling actually looked pretty good out of the box, but I did want to make some minor changes to match the developer.khoros.com look and feel. I made the component title more prominent and I made the message subject text color match the theme colors of the Portal. I also wanted to put my two components (Latest Topics and Latest Solutions) side by side so that both messages lists would be visible "above the fold."
Using the instructions in About Message List Syndication, I created a custom version of the Community Syndication skin and made some small variable overrides. My overrides are outlined in red.
That took care of basic color styling, but I still needed a few bits of styling in the CSS on my external site.
With some help from my colleagues AmyS and RyanPi, I added some CSS classes.
.message-list {
display: flex;
flex-direction: row;
margin-bottom: 40px;
}
.boogie {
flex: 0 100%;
margin: 0 10px;
}
.boogie iframe {
display: flex;
flex: 1 1 auto;
}
I replaced the body script generated in Admin with the following so that it used my custom Community Syndication skin to pick up my variable overrides and made use of my external CSS.
<div class="message-list">
<div class="boogie">
<li:component id="content.syndication.widget.message-list" location-display-id="category:Developer" discussion-style="forums" number-of-messages="6" sort-by="date-desc" component-title="Latest Topics in Developer Discussion" number-of-messages="6" skin-id="devdiscussionsyndication" ></li:component>
</div>
<div class="boogie">
<li:component id="content.syndication.widget.message-list" location-display-id="category:Developer" discussion-style="forums" number-of-messages="6" sort-by="date-desc" component-title="Latest Solutions in Developer Discussion" number-of-messages="6" discussion-style-attribute="accepted solutions only" skin-id="devdiscussionsyndication" ></li:component>
</div>
</div>
The result was what you see today on developer.khoros.com.
How long did this take?
Once I got my testing setup in order, the Message List took me roughly a day to implement. This included coordinating with the Atlas team, recruiting CSS help, testing on stage, and pushing to production.
I will note that the Message List component isn't intended to be displayed two components side-by-side. The component is designed with responsive design in mind and by default, it spans the full width of the area and then collapses to mobile viewports elegantly. But I knew that I wanted these to be next to each other and I also know that the vast majority of Dev Doc Portal users are viewing our docs on a laptop, not on mobile. You might have different circumstances.
I was able to handle the skin variable overrides on my own, but I did need help with some of the other CSS work. I also coordinated with Atlas team members AndyK and LisaI. They set me up to test against our Atlas stage instance. I created my Message List definition in Admin in our stage environment, as well as my custom Community Syndication skin that I would be using for my message lists. I can use this custom skin on any future messages lists that I want to put on the Dev Doc Portal. I added my Dev Doc Portal stage instance domain in the whitelisted section in Community Admin > Content Security. From there, I reviewed the content display in my Dev Doc Portal stage environment to be sure that all looked good on that end.
Once I was happy with what I was seeing, I worked with my Community team to push my custom skin changes to production and added my syndication snippets to the production version of developer.khoros.com. Finally, I added the Dev Doc Portal production domain to the Content Security whitelist and added my custom CSS, script, and code to my landing page and header HTML in my Dev Doc Portal production environment.
And then it was live! It was delightfully easy.
Update: January 2021
Upon the launch of our Developer Blog, I updated the "Latest Topics in Dev Discussions" to include the latest articles from the blog. The component is now titled "Latest Dev Network Content" and includes Developer Discussion forum topics and Developer Blog articles.
Here is the updated li-component code I use to render the Message List component embedded on the developer.khoros.com landing page:
<li:component id="content.syndication.widget.message-list" location-display-id="category:Developer" discussion-style="forums,blogs" component-title="Latest Dev Network Content" number-of-messages="6" sort-by="date-desc" show-kudos="false" skin-id="devdiscussionsyndication" ></li:component>
What's next?
In the future, I see an opportunity to evaluate how the Developer Discussion forum uses tags and labels. That would allow me to create separate Message Lists dedicated to Khoros Communities, Care, and Marketing platforms, and even go more granular to topics like FreeMarker solutions, OAuth questions, Modern Chat questions, and so on...
The next release in the Community Syndication product line will be a commenting syndication feature that will work with forums. My hope is that we'll make that bridge between the community and our dev doc portal even stronger by bringing the capability to start a topic in a component in the Dev Doc Portal and have it mirrored in Atlas.
Can't wait to see what Community Syndication brings next!
