What is Going On with Dev Docs in 2023?
Our Khoros Developer Documentation Portal has undergone some big changes in 2022. We started the year with a new navigation experience, code recipes, use cases, and an expanded Brand Messenger SDK. Much of our focus in 2022 was on creating exciting new products and services that will see tremendous growth in 2023. Part of this focus was on behind-the-scenes work overhauling how we produce and manage developer documentation with next-generation technologies in mind. As the list of supported programming languages, libraries, and tools grows, our methods of delivering clear documentation are also evolving. Our Team I couldn't start this post without acknowledging the tremendous work Javid Hussain (@JavidH) put in. Javid has worked hand-in-hand with the engineering teams, creating detailed documentation for our latest features. He has been an integral part of our team. In his first full year here, he significantly impacted the quality and consistency of our documentation for Khoros Communities, Flow, Care, and Marketing products. A lot of the accomplishments of the dev docs team this year would not have been possible without Javid. Thank you. Community The most exciting thing we've been working on is the developer experience around our upcoming new Khoros Community experience. Because Khoros Community Aurora introduces so many new technologies to our platform, we've been working hard to build out new documentation and ways to share information to help our developer community hit the ground running as new features are released. GraphQL, for example, allows us to explore a different approach to documenting our API. This includes an interactive query explorer that enables you to build and test query requests directly from the Dev Docs Portal against a live demo instance of Aurora. We are also working hand-in-hand with our product teams to bring more developer-oriented features and content into our user interface, enabling you to spend less development time setting up your Community and more time building exciting custom experiences for your users. Brand Messenger Brand Messenger has grown by leaps and bounds over the past year, and it is expected to do even more going into 2023. New features and capabilities are being introduced at an accelerated pace, and because of this, we gave it its own dedicated Dev Docs Portal. The world-class Web and Mobile SDKs made possible by our incredible engineering teams at Khoros connect users to brands in more ways than ever before. As we continue adding new features to Brand Messenger, our documentation will include a library of use cases, recipes, and solutions for virtually any situation. Developer Blog Another area we want to focus on more in 2023 is this Developer Blog. We've had a lot of positive responses to our "How We Built It" series, centered mainly around how different features of Atlas were created. Here are some of the blog posts we created highlighting these features in 2022: Since You Were Gone Component User Profile Hover Card Pronouns in User Profiles Platform Status Banner On the Horizon Our goals in 2023 are to provide additional resources for our developer community that make integrating new features and capabilities easy. This means providing more detailed use case tutorials, helpful tips for the different libraries and technologies on which Khoros' products are built, and troubleshooting issues that may arise during advanced development. We also want our developer documentation to have a more hands-on experience with it. With Aurora, we're working on a dedicated API sandbox for our customers to craft and test queries against our API from directly within the documentation. Not just to get pre-generated responses from queries but to see real-time responses from a working instance of the Khoros Community. Also, in 2023, we want to highlight more of your successes. We invite you to share your work with the developer community and show off some of the tremendous things you've created using our software. We know there are some exciting stories in our community, and we want to help you spread the word about your accomplishments and share some tips and tricks along the way. If you would like to participate in our Developer Blog, email us at [email protected] and let us know.520ViewsSign in to react to this post0Comments2022 Kicks Off With Big Updates to Dev Docs
2021 was an incredible year for the Khoros developer community. We incorporated new products and companies into our developer experience, refined navigation throughout our Developer Docs Portal (DDP). We introduced new features to help visualize use cases and demonstrate best practices. 2022 is set to be even better, with a ton of new features and improvements set to roll out early in the year. A refresh of our documentation's visual design, API reference tools, and an abundance of new content are just some of the ways 2022 is set to be the best year yet for our developer community. Our Growing Team Our Developer Documentation team grew in 2021 with the addition of JavidH. Javid's years of experience and fresh insight have proven invaluable to our Khoros family. He's been working primarily with the Khoros Community and Khoros Flow Developer Docs Portals. Recipes One of the newest features of our DDP platform, powered by Readme.io, is Recipes. With Recipes, we can explore and break down complex API requests and code examples to give context to each individual object, field, variable, etc. Our team has plans to roll out recipes throughout 2022, covering a wide range of use cases, including individualized API request examples that demonstrate the power of our Khoros APIs. You can find some examples of our existing Recipes below: Create a Monitoring Bot (Care) Pass Conversation Control to Agent from Bot (Care) Create a Group Hub with an Avatar (Community) Navigation and UX improvements We took significant steps in 2021 to improve the navigation of our DDP. These include updating our home and category pages to simplify and shorten the navigation flow between the home page and your target content. In 2022, we are taking what we've learned from the initial rollout and applying it to a design overhaul, modernizing the look and feel of our documentation. The UX changes were based on customer feedback with internal and external developer documentation users. Thank you to the customers and internal Khoros teams that we interviewed during our research phase. And a huge thank you to our designer JhilikR and front-end developers ShikherM and AbhishekGu ! Streamlined landing page Up-leveled page feedback tools Persistent header and improved signposting Streamlined landing page Use one less click to get to the product documentation you're looking for. The streamlined hover menu removes the need for a stop at landing pages for each documentation set. Up-leveled Page Feedback Tools Many of you have used the Suggest Edit feature in the DDP Guide pages, but less have used our page feedback component – Did this page help you? widget where you can give a thumbs up or thumbs down vote and add comments so that we understand your rating. We've moved the page feedback widget to the top of the page so that it is move visible. Please give us your ratings and comments to help us improve. We value your opinions and your input improves the experience for the entire Developer community. Keep those Suggested Edits flowing too! We love 'em! Persistent Header and Improved Signposting Internal and external customers expressed frustration with losing their place while working in our Guides and Reference pages. We made the header persistent so that you can easily switch between guides, references, recipes, and changelog. We also added product signposting so that it is clear where you are within our documentation. Improved Tablet Experience to Come Nearly 99% of views on the DDP are from a desktop. That said, we see that there are occasionally folks who need to use the docs from a tablet or mobile device. The new landing page design has been designed for a table viewport. The next steps are to work at navigation and layout improvements on guides, recipes, and reference pages. Developer flows in Maia Maia, the Atlas chatbot now graces the pages of the DDP. Existing customers can do things like file a support ticket, learn about our Titans program, and get to Khoros knowledge bases, ideas boards, and product coaching resources directly from the developer.khoros.com. Existing and prospective customers can schedule a demo, connect with a sales agent, and learn about Khoros solutions. Learn more about the integration in the Developer Blog. SEO Improvements One new project for 2022 that we're working on right now is a site-wide audit on our content's SEO. We want to make our content easier to find through the built-in search. This means renaming some existing content to better match the search queries developers are entering in. We expect these improvements to be continually made across the DDP in January and February. Additional Diagrams, Images, and More We realize not everyone learns best by reading text. So, we are set to add a ton of new diagrams and images to help visualize the data, content, and user experience flow. It's our goal to not only help tell the story of what our APIs can do but to inspire the developer community to map out new ways to get the most out of the APIs.ViewsSign in to react to this postCommentsAtlas Developer Network Updates
Photo by Paul Skorupskas on Unsplash The Atlas team is announcing updates to the Atlas community navigation. But what does that mean to the users visiting the Developer Network and users who are trying to access the Dev Docs from Atlas? New Atlas Menu The main Atlas navigation menu has a whole new look and feel that enables easier browsing and discovery with fewer clicks. When you look t the main Atlas menu, you'll see that we've renamed the Dev Network category to "Developers" and that we've consolidated the separate menu items for developer documentation into a single Developer Documentation item that redirects to developer.khoros.com. Developer Category Page When you click on the Developer option in the main Atlas navigation, you'll see an updated Developer category page. Here, we also consolidated the product card options into one card so that there is a single click to get to developer.khoros.com. We also added components to display Latest Dev Blog posts Latest solutions in the Developer Discussion forum Latest topics in the Developer Discussion forum Developer category kudos leaderboard We're working on minor adjustments to move this content 'above the fold' when you come to the Developer category page. Finally, we up-leveled a component to the right side rail to display a shortcut to developer.khoros.com from the Learning category page for each product solution (e.g., Atlas > Communities > Learning and Atlas > Care > Learning). What's next? Look for an updated landing page on developer.khoros.com in the December/January timeframe. We're simplifying the navigation to get you where you want to go in fewer steps, as well as making some look and feel improvements for better readability and moving our page quality feedback widget to a more discoverable position. (I'll give a quick shout-out to Readme.io our Dev Doc Portal hosting platform while I've got your attention. They have been a great partner to our small Dev Doc team by providing a flexible back-end system that enables us to focus on content. Thanks, ReadMe!)ViewsSign in to react to this postCommentsTwo Community Virtual Developer Training Sessions are Open for Enrollment
The December, 2021 and February, 2022 Community Virtual Developer Training sessions are open for enrollment to all qualified developers. The training event page offers more details on the training format, topics covered, prerequisites, and fees.ViewsSign in to react to this postCommentsKhoros Communities moves to The Cloud
Photo by Alex Machado on Unsplash Nearly two years ago, the Khoros Communities Engineering organization began to move from co-located data centers to AWS cloud services. It's been a long process, but we're nearly complete. Technical Manager Aditya Pandurangi AdityaP , was kind enough to discuss the project with me. Q: Can you summarize what cloud services are and how Khoros Communities uses them? A: A cloud service, at a basic level, is a collection of many data centers that are spread across multiple locations and owned by a cloud service provider such as Amazon Web Services (AWS) or Microsoft Azure. The provider offers companies like Khoros a cloud-based platform, infrastructure, and storage services. In this case, the infrastructure to host and manage Khoros Communities. The cloud service provides a user interface or a set of APIs to request and manage specific hardware with the software of our choosing. The cloud service provider handles the hardware and maintenance, and we're in control of how we allocate resources. Before cloud services, companies had to have their own hardware located in a data center (either on-premise or in a colocated data center with multiple companies). This meant that companies managed the acquisition and maintenance of their own hardware in addition to managing network traffic and other management tasks. Handling hardware failures, hardware replacements, and physically moving the hardware was all in the company's purview. Khoros Communities, for example, had our own servers and equipment running in two data centers: one in Europe (Amsterdam) and one in the West Coast US (San Jose, California). In the cloud, we no longer worry about sourcing hardware, moving it physically, dealing with failures and outages, sourcing data center facilities, or paying data center storage rates. We don’t need to have Khoros employees add, remove, troubleshoot, and replace physical machines when we need more resources or if something breaks. In The Cloud™, everything is done for you. Q: Any downsides? A: There will always be sporadic hardware failures and restarts in the cloud that might temporarily make our services unavailable. That said, Khoros has built-in redundancy to handle failures as gracefully as possible. Also, the costs of using a cloud service over the long term are probably a bit higher because we don’t own the hardware and can’t amortize the cost over the duration of ownership. Despite those points, moving to the cloud is very much a net benefit. It’s allowed us to do cool, new things that we couldn't before, as well as offer our customers a better experience. Q: What does this migration mean for Khoros Communities customers? A. This migration enables us to provide flexibility to our customers in ways we couldn't before. We can now scale our resources to the needs of any customer. For example, some customers host large events where they see a 2-3x increase in traffic on already busy communities. We're talking lots of views and demands on performance. If a game company has a huge game release taking place or if a software company is holding a major event, we can make sure we have enough hardware ready and on standby as needed. Behind the scenes, our Engineering organization has much more flexibility, which benefits the customer. Unlike in the data center, we’re able to adjust our resources on the fly. More app servers needed? Give TechOps a couple of minutes to an hour -- done! Our database is getting overloaded and needs to be doubled in size temporarily? Once again, shine the TechOps signal -- done! We’ve been able to handle outages like never before, and we’ve been able to support many more customers and resources. Q: What does our AWS infrastructure look like? A: This is a high-level diagram. Q: What were some of the challenges you faced? A: The new environment presented a few challenges. AWS uses a paradigm of separate, siloed regions for different environments (such as QA vs. Production). This was a change from our datacenter infrastructure that used region-agnostic services. In the cloud, each region requires its own service deployment. This created extra work for teams that migrated their services to the cloud, but it was worth the trouble. Our infrastructure is more resilient -- there isn’t a single shared point of failure. An issue in one region does not affect the others. The migration required several teams within the Community Engineering organization to improve services and update workflows. We broke large, multi-purpose services into smaller parts with a more narrow focus. While that led to improved security, technology updates, and better performance, we had to shake off old habits and adjust to multi-step processes. Q: How big was this project, and how long has it been in progress? A: After a couple of false starts, we created the first JIRA ticket for this project on May 15th, 2018, so I think we can consider that the beginning of the project. This migration has been a massive undertaking that’s taken the effort of many teams. A multi-year project takes endurance. For fun, we hung a child's growth chart (like something you'd use to track height over time) in the San Francisco office. Each week, we'd update the chart. This worked great, until Covid when we shut down the office to shelter in place. We got a chance to go back to the office in April to pick up personal items. The chart was still there and we updated our progress. (We got a little lazy with that chunk in the middle where we just drew a simple line.) Later on, Jake Rozin (JakeRo), an engineer in our Customer Operations group, built a UI for us to track the status of community migration. Here's a simplified, sanitized version of the page as we were just finishing moving communities out of the Amsterdam data center. Q: What kind of coordination did the migration require? How many different teams had to work together to make this happen? A: This effort has taken the coordination of many different groups. The primary teams involved have been Technical Operations (TechOps), Application Operations (ApOps), Information Security (InfoSec), and Rocket. Each of these teams has played a vital daily role in the AWS migration process. In addition, all the teams responsible for individual microservices were involved. These teams have had to convert their services to use our new service deployment pattern in AWS, including Dockerizing their service and coordinating with the groups above to migrate and set up infrastructure. Q: What's the Rocket team? A: Rocket is an Engineering team in the Community organization. Essentially the team acts as the glue between TechOps and Engineering. While TechOps deals with networking and setting up/monitoring our infrastructure, the Rocket team works one layer above. We design and implement deployment patterns and pipelines used to integrate Khoros Communities services with our AWS infrastructure. Engineering teams across the Community organization consult us about using our deployment patterns and the best ways to support different service types. Rocket also builds internal tools. For example, we built one service to determine whether we can scale a community to another node and another to find the correct service to perform cloud-based operations (such as adding/removing targets from a load balancer or creating a CDN distribution). Other projects include: improving our security practices and leveraging new cloud-based security options, such as encrypted parameter stores and policy-based access controls (in conjunction with TechOps and InfoSec) updating our current provisioning and de-provisioning processes to work with the new cloud infrastructure and paradigm (in conjunction with TechOps) Q: Did the Rocket team have to build services or tools for the migration process? A: We did! Unfortunately, we are in the process of patenting them. Once we get those filed, we'll write another post with the details 😁 Q: What have been the major milestones for the project? A: We’ve had several major milestones throughout the AWS migration. Proof of concept: Our first milestone in 2018 was building and testing the AWS environment and developing a migration plan. We started with a basic cutover process. This initial proof of concept proved that Khoros could effectively host communities in AWS. The plan slowly evolved to more detailed cutover steps and enabled us to plan for the complete migration. Atlas (Khoros's community) was among the first communities hosted in the cloud. Iteration and automation: Process iteration led to more detailed cutover steps as well as automation services. That brought us to our next major milestone, where we could pass customer migration tasks to our AppOps team and free up Rocket team resources. EMEA community migration and first data center shutdown: End of October/mid-November of 2019, we moved every EMEA customer out of the Amsterdam colocation and into AWS. From there, TechOps completely shut down the Amsterdam data center. AMER community migration: As of Apr 14th, we reached our next milestone. All our AMER communities are in AWS. All that remains are the final milestones -- completing service migration and shutting down the US datacenter in San Jose. Once this happens at the end of June, our AWS project will finally be complete! Q: Can you share and charts or metrics showing improved performance for customers due to the migration? A: Sure. The following charts show the drop in beacon times pre and post-AWS migration. Beacon time is our way of measuring the time it takes a human (we filter out bots) to load a page on a community. Lower beacon times signal that the page being viewed loaded faster. (The numbers on the Y-axis are time in milliseconds.) Two of the customers featured in these charts have heavily trafficked communities. I picked the third at random. You can see that they all showed nice improvements post-migration. Customer 1 Customer 2 Customer 3 Q: Nice! What is it about AWS that lowers beacon times? A: There are a few factors. Our servers in the datacenter were starting to age and the AWS servers are newer, have better CPUs, and thus perform better. In addition, we started routing all traffic through Cloudfront as a CDN, which serves as a caching layer. I imagine that AWS also optimizes the route by which Cloudfront reaches the load balancers for speed. Thanks so much, Aditya! We appreciate your insight and all the details. We'll end here, but before we do, let's give a shout out to all the folks who made the AWS migration possible: Rocket: JonL,eddielo), AdityaP , LauraPe , KaranS , hernan_vinuesa TechOps: BillKr, CanC, ChrisSa, DanielA, DavidSu, EricV, GeorgeB, GokulN, KunjalS, MarcS, MarkJ, MattW, MichaelCa, TauqeerA, WillY Information Security: BryanM, JuanCo, ManjunathM, MinhN, MohanaC, PeterN, SoumyaR, SuyashM Application Operations: kh-mso, ArunkumarG, DimitarI, Georgi Todorov, MichaelM, NicholasD, RonT, (WeiS)ViewsSign in to react to this postCommentsWelcome To Our New Developer Blog
Welcome to our new Developer blog! It's our goal to not only create an excellent resource for news and information about our products that matters most to developers but to share insights and knowledge about software engineering from members of Khoros and our community at large. This includes top tips, API changes that matter to you, and success stories with insight into how you can get the most out of Khoros' APIs. At Khoros, we love our developer community. The backbone of any great enterprise is its engineering team, and we wanted to create a blog that speaks directly to developers. This means diving deeper into subjects that matter to engineers working with Khoros products, and providing useful information that goes beyond the high-level perspectives blogs with a wider audience are limited to. The goal of this blog is to not only share tips and tricks about our products, but to pass on some of the things our engineering teams have learned while creating them. Here are some of the types of posts we have planned to share: Feature/product highlights Development tips and tricks API updates Use cases and solutions Question and answer Success stories (both internal to Khoros and shared by customers) Upcoming updates and new features We're excited about the opportunity this blog provides us to speak directly to our developer community, sharing insight into some of the cool things we've been working on and how they will empower you to do even more. Want to Share a Post of Your Own? Have an idea? Do you have a success story or solution that you want to share? Please feel free to email us at [email protected] and let us know you'd like to submit a guest blog post. We would also be thrilled to receive blog topic suggestions so we can cover them in a future post.ViewsSign in to react to this postCommentsContent Workflow API Updates are Here
Khoros' Content Workflow feature in Khoros Communities enables you to create a comprehensive content workflow process including authors, editors, and publishers that each play an important role in crafting, editing, and publishing TKB and blog posts for your community. This includes not only the crafting of new content but also to enable users to nominate, approve, and promote forum messages to TKB articles. With Khoros Communities 21.1, we have introduced these features to Communities API v2. The additions are available during message creation and updates. In this post, we'll uncover a few of the changes to the API, and you can use them to get more out of your Khoros Communities projects. Content Workflow Roles Contextual roles enable you to assign users access to various steps on the content workflow process. These roles break down at the most basic level to: author, editor, and publisher. That said, the permissions break down at a much more granular level. Here is a quick breakdown of the different contextual permissions a user can be assigned: Within the user_context object (related to promoting a forum message to a TKB post): Nomination (First Step) can_nominate - Whether the authenticated user can nominate a forum topic to be converted into a knowledge base article. Approval (Second Step) can_approve - Whether the authenticated user can approve a forum topic's conversion to a knowledge base article. can_reject - Whether the authenticated user can reject the nomination of a forum topic's conversion to a knowledge base article. Promotion (Third Step) can_promote - Whether a user can start a TKB post from a forum message. can_schedule - Whether the user in the current context can schedule the post for publication. Within the message_workflow_context object (related to new blog/TKB posts): Authoring (First Step) can_submit_for_review - Whether the user in the current context can submit the article for review. can_recall - Whether the user in the current context (usually the post's author) can recall the post directly back to the author. Editing/Review (Second Step) can_edit - Whether the user in the current context can edit the post. can_return_to_author - Whether the user in the current context can return the post to the author. can_submit_for_publication - Whether the user in the current context can submit the post for publication. Publishing (Third Step) can_publish - Whether the user in the current context can publish the post. can_return_to_review - Whether the user in the current context can return the post for review. can_schedule - Whether the user in the current context can schedule the publication of the post. Content Workflow Actions We've created a new Content Workflow object, which incorporates directly in the Create and Update Message endpoints. Using this object, you can set and update the status of messages as they progress through the content workflow process. For example, a new post would have a save_draft or submit_for_review workflow action placed on it during its initial creation. This would either save the draft for future edits or label it as ready to review by an editor. Those users, once the review is complete, can then update the message with a submit_for_publication or return_to_author workflow action to either pass the message on to a publisher or return the message to the author to edit and resubmit. Finally, a publisher can apply a publish, schedule_publication, or return_to_editor workflow action to either publish the message, schedule a future publication, or return the message to the reviewer for additional review. There are many different actions that can apply to a message throughout the process. You can find a list of them in our API reference. LiQL Queries We've added a host of new LiQL capabilities to support the content workflow feature. This will enable you to retrieve messages by their workflow status, determine a user's contextual permissions for a given message, and more. We've updated the following LiQL reference pages: messages user_context We've added several new LiQL reference pages for the new content_workflow collection: content_workflow message_workflow_context message_statuses message_draft_history Use Cases We've documented several use cases to introduce the new API features, as well as to bring some context to how these features work in practical application. These use cases include: Nominate a Forum Message Review a Message Schedule Publication Submit a Blog or TKB Message for Review The new Content Workflow API is available to Khoros Communities starting with release 21.1.ViewsSign in to react to this postComments
520Views
0Comments
You’ve seen all recent content