5. Technical writing and online help improvements

5. Technical writing and online help improvements

This chapter follows my writing process from research and scoping through release work to improvements readers can see. It includes my individual writing examples and a broader comparison of help changes made across the documentation team.

5.1 Establishing the documentation scope

My product-writing work involves determining what changed, what users need to understand, and which topics need updating. I use Jira requirements, product and test environments, design material, and SME discussions to define scope and resolve uncertainty. The examples below show how that research shapes the guidance I prepare.

The interface-update review shows the value of that scoping work. In August 2024, I reviewed a new SOTI MobiControl interface with a product colleague, identified the affected topics, and described a smaller set of targeted changes instead of the larger reorganization originally anticipated. For a reader unfamiliar with the product, this meant updating the instructions where the interface had changed instead of reorganizing unrelated help.

5.2 Signal properties conditions and events

While researching Signal documentation, I requested complete inventories of Signal properties, supported device families, system components, configurations, and events. Signal helps administrators monitor device conditions and act on them; incomplete lists would leave readers unsure which inputs and events the feature actually supports. My documentation improvement was to seek the missing scope before writing or revising guidance.

This research supported my understanding of Signal, which helps administrators monitor device conditions and act on them. Across the team, the help evolved into a wizard-oriented structure covering conditions, actions, schedules, properties, events, examples, upgrades, services, troubleshooting, and macros.

5.3 Device audit logging

For Device Audit Logging, I investigated design material and sought clarification on the location and composition of generated device logs. Readers need to know where diagnostic records appear and what each log contains; an inaccurate location would make a troubleshooting procedure unusable. When the available information was uncertain, I pursued another SME rather than relying on an unverified interpretation. The work included two SME conversations in February 2026.

This example connects support-style investigation with writing: I identified the questions the guidance needed to answer. The certificate-deployment before-and-after shows a separate, directly inspectable example of turning technical detail into a guided procedure.

5.4 Declarative and reactive application policies

I sought SME clarification on how declarative and reactive app policies differ, including update behaviour, managed application configuration, connectivity conditions, retry behaviour, and activation predicates. I then checked a draft with the SME. I discussed the draft with an SME in February 2026.

These distinctions affect how administrators interpret an application policy. Clarifying the behavior helps writers explain the appropriate workflow and organize guidance by platform.

5.5 Apple enrollment documentation

I reworked the Apple enrollment overview to clarify the differences between enrollment methods and added a capability matrix to help administrators compare their options. I also added dedicated guidance for account-driven device enrollment on iOS.

The reader-facing Apple help comparison shows the broader reorganization, while the Apple enrollment before-and-after isolates a specific committed overview change. These views answer different questions: how the section evolved, and what one selected revision actually changed.

Across the team, Apple enrollment help was reorganized around device-based, user-based, and account-driven enrollment. The structure also clarified macOS and tvOS guidance, Apple Business Manager terminology, and supporting policy-management tasks.

5.6 Additional feature research

My additional investigations covered Microsoft outbound email and Office 365 SMTP, feature scope and designs, and the move of Enterprise Apps from Policies/App Policies into Device Resources. I also worked on documentation updates with review constraints, comparisons between draft and mainline help, feature and device-support research, and a runtime note for release 2026.1.2 and later.

Additional exploratory work included eSIM-related research and Signal documentation research.

5.7 Release procedures and structured delivery

I follow a structured release process: assess and prioritize the request, research the feature, draft the guidance, obtain SME and peer review, publish, and communicate completion. I use requirements, QA test plans, SME interviews, and sprint demonstrations to check that the help reflects the intended behavior.

I contributed an earlier version of the release-note procedure with a colleague. The described process uses a Jira request, a shared Word draft, Technical Writer review, manager peer review, and the subsequent publishing workflow. The procedure later evolved, so I retain my contribution without claiming authorship of every part of its current version.

The following sections show the reader-facing result of that writing work, with the Writing collection providing exact before-and-after source pairs.

5.8 Comparing the help from the reader perspective

SOTI MobiControl provides the case-study setting for this work. The transferable contribution is clearer procedures, better navigation, and more useful technical context.

The earlier research and release examples explain how a writing task started. The before-and-after collection shows selected source revisions at the other end of that process. Together with the section-level comparison below, they make both the editorial reasoning and its visible result easier to follow.

I compared SOTI MobiControl help from December 2023 with June 2026 to understand what changed for readers: navigation, task guidance, platform coverage, completeness, and layout. The comparison uses saved revisions from December 20, 2023 and June 12, 2026.

The figures below describe changes across the documentation team. Topic counts follow the help navigation, excluding related-link entries; the Device Details and Actions area covers topics spread across several sections.

Command-step counts include substeps. Media counts include figure containers, images, and embedded objects, so they are not counts of unique screenshots. These figures describe the structure and coverage of the help.

5.9 Profiles and the SSO content cluster

Profiles has the largest change footprint in the comparison. The current structure gives readers more ways to browse by operation, configuration category, platform, and payload/configuration area. Assignment options, access permissions, assignments, queue management, and stopping deployment sit closer to the main profile tasks. Platform coverage includes additional ChromeOS/macOS Wi-Fi, mobile private network, encrypted DNS, local users, Google Account, declarative profiles, and certificate-related content.

Single Sign-on illustrates the navigation change: one navigation entry became a group of 26 topics covering Android, Imprivata, Apple/macOS, Extensible SSO, Kerberos, and Microsoft Authenticator workflows. The group combines new guidance with topics moved from other sections.

Profiles remained an area of ongoing improvement, with new guidance and clearer organization across platforms.

5.10 Selected writing improvements

Each example compares a selected revision with its previous version to show a specific writing or review decision. Step counts include substeps, and image counts refer to images included in the topic.

The comparison collection also includes my profile-assignment peer review and an AI-assisted draft of a new Apple dynamic-configuration task. These examples show how I approach editorial feedback and new-topic authoring.

The comparison also covered Samsung application-firewall and manually uploaded-certificate guidance. Later revisions continued to refine these procedures: the June FileVault topic had 14 steps and 5 images, compared with 15 steps and 7 images in the March draft. The certificate overview developed into an 11-step procedure for manually uploading certificates.

Later revisions incorporated several of my profile-assignment review suggestions: a direct opening, a separate navigation step, consolidated filter guidance, and a related link. My May 2026 revisions further improved the Wi-Fi, FileVault, and API examples, including corrected application/profile wording in FileVault guidance.

5.11 Global Settings

Global Settings became easier to browse by console settings area. The organization brings together Device Agent and Plugin, Enterprise Migration Certificate, App Store License Management, APNS, Automated Device Enrollment, API clients, Device Maintenance, Terms and Conditions, LDAP, and Google Workspace bindings.

Outbound email illustrates how related guidance can sit closer to the task. Notification help appears under Monitoring, while Global Settings explains viewing connections and sending test email. Related additions cover Microsoft Entra applications, SMTP outbound connections, Apple root certificates, Chrome Enterprise bindings, Cloud Link, and deployment-server settings.

5.12 Device details actions and updates

The Device Details and Actions area grew through targeted additions rather than a single root-node rebuild. The comparison includes device-action behaviour, details and search, update workflows, eSIM policy management, Windows OS images, the Updates dashboard, and rollback handling. Within the defined path-based scope, task topics increased from fourteen to thirty-two.

These help improvements connect to actual administrator tasks. My contributions included updates-dashboard and rollback guidance in April 2026.

5.13 Policies

App Policy content expanded from twenty-six mapped topics to fifty-four and was grouped by Android, Apple, Windows, Enterprise App Store, and management operations. Signal grew from eight mapped topics to twenty-two, with wizard steps and nearby property, event, example, upgrade, service, troubleshooting, and macro references. Compliance and Enrollment Policy sections gained permission and label-management support.

My contributions included declarative and reactive app-management guidance, Signal material, peer-review revisions, and policy-related updates. Together, these changes help administrators understand the feature and find the relevant procedure.

5.14 Apple enrollment

Apple enrollment help was reorganized around management types and enrollment choices. It covers a capability matrix, device-based and user-based flows, account-driven enrollment, macOS and tvOS, Apple Business Manager, Managed Apple Accounts, supervised enrollment with Apple Configurator, discovery services, and policy permissions and labels.

A broader comparison of Apple enrollment and related topics shows growth from 94 to 102 topics, 359 to 377 command steps, and 51 to 150 media markup elements. This broader selection includes more topics than the Apple Enrollment Policies navigation counted in the summary table.

5.15 Certificates

Certificate help became more lifecycle-oriented in the comparison. It brings together manually uploaded certificates, dynamic deployment, certificate-authority integration, templates, Subject Alternative Names, dashboard visibility, and device-level management. The mapped scope increased from six topics to thirteen.

I drafted certificate documentation, requested reviews, and incorporated feedback. Other writers contributed dashboard and template changes to the same section.

5.16 Consolidating related guidance

Consolidation brought overlapping guidance into clearer destinations while retaining reference topics where readers needed settings or configuration details.