Can Technical Writers Exist in an Agile Dev Team?
Technical writers are an important part of any software development team working on projects or products with customer-facing components. Whether you're creating a simple UI-based tool for customers without any technical experience or an API with complex parameters that pose a challenge to even the most experienced developers, a technical writer bridges the information gap between your development team and the end-user. So, how do you integrate a technical writer into your agile development environment? What role(s) does a technical writer perform within your organization's development team? In this post, we will cover some tips for doing just that! Scrum and Planning Meetings Technical writers are often considered outsiders within an engineering environment. They are typically outnumbered by engineers and frequently work with multiple engineering groups at the same time. This makes it easy to see them as an outside entity rather than a member of the scrum team. However, this perception doesn't take into account the many hats a technical writer wears. A technical writer is like an embedded reporter, writing stories about the projects the scrum team(s) are working on. Those stories benefit from having detailed knowledge of not only what the project is about, but what decisions went into its creation. Knowing why it made more sense to create a feature with one set of parameters over another helps the writer to explain the benefits (and potential snags) to the audience. Consider including technical writers in scrum meetings, as well as in planning sessions where new projects are conceptualized. This will not only provide much-needed context to the writer but save your team time explaining these details later on. Location One common mistake organizations make in their office layouts is to group technical writers in with marketing, design, etc., and sit them with those teams, away from the engineering department. In an in-person working environment, you should consider sitting your technical writers with the engineers. Separating them physically prevents the writers from hearing and absorbing the day-to-day discussions that happen, often resulting in missed opportunities for documenting changes as they occur. Development Environments It's important for technical writers to have access to the same level of development/testing environment as the engineering teams. Even if it's a local deployment of a nightly build, being able to explore and see the code in advance of the documentation being required gives writers a head start on their work. The amount of time the writer has to use and document the upcoming release, the better the documentation. This also allows technical writers to fill another important role that they often do: testing. In order to document a new feature, writers test their documented steps. This enables them to not only discover bugs in their documentation but often to uncover bugs in the code and/or product ahead of release. Time The most valuable commodity of any professional's day is time. Putting aside time for the technical writer to interview members of the team is essential to good documentation. Not only does it allow the writer to ask questions to gain a better understanding of the product, but it also gives your team the opportunity to discover and correct any inaccuracies in the documentation prior to its publication. Product managers, project managers, engineers, and architects should set aside a block of time to work with technical writers on any new significant release. This time may be used doing technical checks of documentation drafts or simply syncing up with the writer to go over any upcoming changes they need to be aware of. Forums and Chat Channels Especially in larger organizations, engineering scrum teams often have private channels where they can share information with one another outside of in-person meetings. This may be internal boards within your Khoros Communities site, team chat channels, issue tracking platforms, collaborative software, etc. Inviting the technical writer into this space is a great way to ensure they stay informed about what the team is working on, and whether or not changes are in the works that may require additional documentation. It also gives them the ability to ask questions outside of scheduled meetings and emails that can be quickly answered without the need to set aside a set time. Summary Technical writers are a unique part of any organization. They are not themselves engineers, but they typically work best in an environment where they are amongst them. In an Agile environment, technical writers don't just provide documentation. They perform multiple roles that touch on engineering, quality assurance, product management, and of course documentation. Do you have technical writers on your team? What are some of your tips, tricks, and best practices? Share them in the comments section below!568ViewsSign in to react to this post0CommentsHow We Built the KB Audit Flow Part 2: Audit Checkbox (Updated)
The KB Audit Flow requires two components to work. The first is an audit checkbox that enables members with specific roles to mark a KB article as "audited" from the front end. This checkbox includes the initial check and confirmation. The second component is the 'Last Reviewed' Information component which displays the date and time of the last audit of the KB article. That component is displayed for all visitors, regardless of their role(s). It does, however, check the member's roles to determine whether or not to additionally display the audit checkbox featured in this post. In this post, we will create a new audit checkbox component. Note: These instructions cover the method for creating the component using the Community Plugin SDK. For an easier UI-based approach, we recommend using Studio to create the component. The content of the file below remains the same. We highly recommend reading the other two posts in this series to get a better understanding of the other components and prerequisites required for this component to function properly. How We Built the KB Audit Flow Pt. 1 How We Built the KB Audit Flow Pt. 3: Review Date Display Create a Custom Endpoint A custom endpoint enables the audit checkbox component to send the "last reviewed" timestamp to Khoros, updating the date and time the article was last audited. To create this custom endpoint: Navigate to Studio > Endpoints Select the New Endpoint button Enter last-reviewed-date in the title field Select Save Enter the following in the View Content field: <#assign msg_id = http.request.parameters.name.get("msg_id", "")?string /> <#assign date_time = http.request.parameters.name.get("date_time", "")?string /> <#if msg_id != ""> <#assign lastReviewedDateResponse = restadmin("/messages/id/${msg_id}/metadata/key/custom.message_last_reviewed_date/set?value=${date_time}") /> </#if> Select Save This creates a new custom endpoint which passes the message identifier and datetime to Khoros. It is utilized by the Audit checkbox component we are creating next. Create LastReviewed-Audited-checkbox.ftl file The process for creating the checkbox component is pretty straightforward. To start, create the LastReviewed-Audited-checkbox.ftl file as a component. For example: /res/components/LastReviewed-Audited-checkbox.ftl. Here are the contents of that file: <style> .audited-component-checkbox{ margin-top: -20px; margin-bottom: 35px; } label.lia-form-label.audited-label-set { padding-top: 4px; font-weight: bold !important; float:left; } .litho-audited-checkbox-style{ float: left; } .lia-form-label-wrapper.audited-label-float{ float: left; } .lia-inline-confirm.confirm-label-float{ float: right; margin-top: 4px; margin-left: 12px; } a.litho-tkb-audited-deny { cursor: pointer; } a.litho-tkb-audited-approve { cursor: pointer; } .hide-article-component-here{ display:none; } </style> <#-- <#import "article" as com> --> <div class="hide-article-component-here"> <@component id="article"/> </div> <#assign message_uniqueId = -1 /> <#if env.context.message??> <#assign message_uniqueId = env.context.message.uniqueId /> <#assign lengthOfDomain = env.context.message.webUi.url?index_of("/t5") /> <#assign communityDomain = env.context.message.webUi.url?substring(0,lengthOfDomain) /> </#if> <#assign communityId = community.id /> <#-- REST call to get the user's roles --> <#list restadmin("/users/id/${user.id?c}/roles").roles.role as role> <#-- Look for the role name you want to display content for --> <#if role.name?? && ( (role.name == "Administrator") || (role.name == "Documentation") )> <div class="audited-component-checkbox"> <div class="lia-quilt-row lia-quilt-row-standard lia-quilt-row-first lia-quilt-row-last"> <div class="lia-quilt-column lia-quilt-column-24 lia-quilt-column-single lia-input-edit-form-column"> <div class="lia-quilt-column-alley lia-quilt-column-alley-single"> <div class="lia-form-row lia-form-auto-subscribe-to-thread-entry lia-form-row-reverse-label-input lia-form-row-checkbox litho-audited-checkbox-content"> <div class="lia-quilt-row lia-quilt-row-standard litho-audited-checkbox-style"> <div class="lia-quilt-column lia-quilt-column-24 lia-quilt-column-single"> <div class="lia-quilt-column-alley lia-quilt-column-alley-single"> <div class="lia-form-label-wrapper"> <input class="lia-form-auto-subscribe-to-thread-input audited-checkbox" id="LastReviewAudited" name="auditedCheckbox" type="checkbox"> </input> </div> </div> </div> </div> <div class="lia-form-label-wrapper audited-label-float"> <label for="LastReviewAudited" class="lia-form-label audited-label-set"> Audited </label> </div> <div class="lia-inline-confirm confirm-label-float confirm-label" style="display:none;"> Confirm? <a type="submit" class="litho-tkb-audited-approve"> Yes </a> / <a type="submit" class="litho-tkb-audited-deny"> No </a> </div> </div> </div> </div> </div> </div> <#break> </#if> </#list> <@liaAddScript> ;(function($){ $(".audited-checkbox").click(function(){ $('.confirm-label').toggle(); }); $(".litho-tkb-audited-approve").click(function(){ $(".audited-checkbox").attr("disabled", true); <#if message_uniqueId != -1 > <#assign aDateTime = .now?iso_utc> $.ajax({ type:"POST", url:'${communityDomain}/plugins/custom/lithium/${communityId}/last-reviewed-date?date_time=${aDateTime}&msg_id=${message_uniqueId}', contentType: 'application/json', success: function(res) { console.log(res); console.log("Added"); location.reload(true); }.bind(this), error: function(xhr, status, err) { console.error(xhr, status, err.toString()); console.log("unable to add last_reviewed_date field into DB"); }.bind(this) }); </#if> $(".audited-checkbox").prop("checked", false); $('.confirm-label').hide(); }); $(".litho-tkb-audited-deny").click(function(){ $(".audited-checkbox").prop("checked", false); $('.confirm-label').hide(); }); })(LITHIUM.jQuery); </@liaAddScript> Code Breakdown In this section, we will examine some of the parts of the component's code to better understand how the component works. <style> ... </style> This section of the file sets the CSS styling for elements within the component. <div class="hide-article-component-here"> <@component id="article"/> </div> This section loads the current article in this component to get the message information, including the message's unique identifier. <#assign message_uniqueId = -1 /> <#if env.context.message??> <#assign message_uniqueId = env.context.message.uniqueId /> <#assign lengthOfDomain = env.context.message.webUi.url?index_of("/t5") /> <#assign communityDomain = env.context.message.webUi.url?substring(0,lengthOfDomain) /> </#if> <#assign communityId = community.id /> This section extracts the message's uniqueId, enabling the component to fetch information for the specific article. It also references the community ID, which we use later in a POST call to update the last reviewed timestamp. <#list restadmin("/users/id/${user.id?c}/roles").roles.role as role> This section initiates a REST API call to retrieve the member's role. <#if role.name?? && ( (role.name == "Administrator") || (role.name == "Documentation") )> This section compares the retrieved role name to pre-defined names of roles that we want to enable access to the Audit checkbox. <input class="lia-form-auto-subscribe-to-thread-input audited-checkbox" id="LastReviewAudited" name="auditedCheckbox" type="checkbox"> ... </input> Here we create the checkbox with the audited-checkbox class which is referenced in the liaaddscript Freemarker section at the bottom of the file. <#if message_uniqueId != -1 > <#assign aDateTime = .now?iso_utc> $.ajax({ type:"POST", url:'${communityDomain}/plugins/custom/lithium/${communityId}/last-reviewed-date?date_time=${aDateTime}&msg_id=${message_uniqueId}', contentType: 'application/json', success: function(res) { console.log(res); console.log("Added"); location.reload(true); }.bind(this), error: function(xhr, status, err) { console.error(xhr, status, err.toString()); console.log("unable to add last_reviewed_date field into DB"); }.bind(this) }); </#if> Here, we are creating a variable containing the ISO UTC date and time and applying it to an endpoint dedicated to updating the last reviewed date through a POST request to a custom endpoint we configured in Studio. Note: This post's script examples and descriptions have been updated to the latest method used by our Atlas team. The new method uses a custom endpoint to handle the data transfer.ViewsSign in to react to this postCommentsHow We Built the KB Audit Flow Pt. 1
Trust in the accuracy of your Knowledge Base articles is essential to building trust and confidence between your visitors and the content they're interacting with within your knowledge base. One way of ensuring that each KB article is current and accurate is frequent and routine audits on that content. The audit process should be straightforward for your authors, administrators, and moderators, and transparent for your readers. To make this process as seamless and easy as possible on Khoros Atlas, we created an auditing solution that enables members with the appropriate permissions to set the article as "audited" and to display the date and time of the last audit to visitors. In this three-part series, we're going to take a detailed look at how we built out this auditing solution in Khoros Atlas. We highly recommend reading the next two posts in this series to get a better understanding of the other components and prerequisites required for this component to function properly. How We Built the KB Audit Flow Pt. 2: Audit Checkbox How We Built the KB Audit Flow Pt. 3: Review Date Display Concept Our 'Last Reviewed' component enables members with the appropriate roles (defined in the 'Last Reviewed' component we will create in this guide series) to see a checkbox in the sidebar of each KB article enabling them to indicate that the article has been audited. This "Audited" checkbox. When the box is checked, the time and date are saved as part of the audit trail. Note: The role(s) required to see the Audited checkbox are set within the "Last Reviewed" information component we will create in the second part of this blog series. Once that data has been saved, it is then displayed in the sidebar. This enables visitors to see when the article was last reviewed. This enables them to gauge how up-to-date the information in the KB article is. Member Flow For permissioned members, auditing an article is as simple as reviewing it on the front end and selecting the Audited checkbox. Once done, a confirmation message appears enabling the member to confirm the audited state by selecting Yes, or cancel it by selecting No. Once confirmed, the date and time data is saved and that date and time become the new "Last Reviewed" date displayed to all visitors in the sidebar. Prerequisites Before this functionality can be added to the Khoros Communities instance, we need to make a few changes on the back end to create a space where metadata containing the audit timestamps and status for each message will exist. This requires a few steps that Support can assist you with. To get your instance ready to work with the Audit Flow, simply submit a support request using the Case Portal and request that your Communities instance be configured to support Audit Flow. Case Study: Khoros Information Experience Team Our Product Content Experience Team is responsible for writing and maintaining the knowledge base (KB) articles for Care, Community, Marketing, CX Insights, and Khoros Flow. This includes a library of hundreds of articles, each focused on information that evolves alongside the products. The Challenge As you could imagine, keeping all of this content updated is a huge responsibility. Outdated information in our knowledge base leads to confusion and wasted time. We needed a solution that accomplished the following: Instill confidence in visitors that the article they're reading is updated and accurate Enable team members to record their audit of existing KB articles from the front end Provide a visible label on each audited article with the time and date of last review Create a process for determining which articles should be prioritized for audit Execute audits in coordination with internal engineering and product teams The Technical Project To reach these goals, we partnered with the Atlas team, as well as our internal engineering and product partners, to create both a technical solution and team workflow. The technical side of the project required some development work on Atlas. This included: A new table in the database to store the "last reviewed" information Metadata fields to represent the information in each article A component that enables the frontend audit checkbox for users with specific roles A component that displayed the "last reviewed date" of each article to all visitors With these additions in place, our team members with the Administrator or Documentation role can mark a KB article as audited from the front end, and have the date and time of that review displayed to all visitors, regardless of their assigned role(s). This accomplished the feat of both simplifying the review process and making a functional improvement that our visitors can benefit from. Tackling the Audit Process The next thing we needed to achieve was the active auditing of over 1,000 TKB articles currently in Khoros' knowledge base. Many of these articles were written years ago, and our team (at the time) was very small. We partnered with various teams across Khoros to assign articles to subject matter experts, so it wasn't just our content team that was reviewing content. If the content was 100% accurate, it would be marked as audited. If not, we created a ticket in Jira and assigned a content team member to update it. This cross-functional auditing pass enabled us to audit ⅓ of the KB articles in our library in six months. This approach brought with it a number of challenges. It was a logistical feat to coordinate with all of the teams and ensure deadlines were met. Additionally, we weren't entirely sure that every article receiving the bulk of our focus was actually being used by our customers. So, we adjusted our approach for the second phase of our audit. Instead of tackling the entire library of articles at once, we instead focused on the following articles: Articles with the highest average views per day Articles with an average of at least one view per day since it was published This was accomplished by examining the publishing date of each article, as well as its total views. With this information, we could determine the average number of views for each day since the article was published. Articles with the most average views per day received the highest priority. The rest of the articles with at least one visit per day would receive an audit once the first batch of articles is complete. Now that our team has grown, we are able to set achievable goals and divide the work amongst our writing staff so that our efforts are targeted so each audit has the maximum possible impact on our overall customer experience.ViewsSign in to react to this postComment
568Views
0Comments
You’ve seen all recent content