# Better Editor guide ## Purpose Better Editor is a free Smaller Chunks work-item field control for Azure DevOps. It edits an existing rich-text HTML field with a modern icon toolbar. It is a supporting tool alongside the six-product end-to-end suite, not another stage in that process. It requires no subscription or license key. Installing Better Editor does not automatically replace all rich-text editors. Each control is bound to one field on one work-item type through the process layout. The field retains its existing data; there is no separate editor database. Plain-text fields and the Discussion/comments feed are not supported. ## Set up an existing or new field An administrator with the appropriate process permissions configures the inherited process: 1. Open Organization settings > Process and choose the inherited process used by your project. 2. Choose the work-item type, then Layout. 3. If you need a new field, use New field to create a Text (multiple lines) rich-text field first. Skip this step for an existing field such as Description or Acceptance Criteria. 4. Choose Add custom control. In Definition, select Better Editor, or Better Editor (Testing) for the testing edition. 5. In Options, choose the Rich-text field. This is the field whose content the editor will read and update. 6. In Layout, choose a label, page and group, then select OK. Creating a group here only determines placement; it does not create a field. 7. Open a work item and check the field's content, editing and native saving. 8. If desired, hide the original field control so the same field is not displayed twice. Hide the control; do not delete the underlying field. Repeat for each field and work-item type. Definition, Options and Layout are Azure DevOps's custom-control configuration tabs. Selecting an item in the dropdown leaves it visible as the selected choice; that alone does not mean two controls were added. Placement is managed by the process layout, not by dragging the editor outside its host area. ## Edit and save Type or format content in the editor. Changes are sent automatically to the bound field on the current work-item form. They make the form dirty so Azure DevOps can enable Save or Save & Close. There is no separate Apply-to-field step. The editor does not save the work item itself: use the native Save or Save & Close button to persist the edits. Updates are checked against the current field to avoid silently overwriting outside changes. If an error or conflict is shown, preserve a copy of your draft and resolve the reported problem before continuing. Loading existing content alone should not rewrite the stored field. Imported rich HTML may be sanitized and normalized when edited, so review complex imported content before saving. ## HTML controls HTML mode offers headings, bold, italic, underline, strikethrough, lists, alignment, links and code. Use text color and highlight controls for emphasis. Table controls insert tables, add or delete rows and columns, merge or split cells and toggle header rows. Some commands require placing the cursor in the relevant content, such as a table cell, or selecting text first. The toolbar uses Lucide icons; hover labels identify commands. ## Markdown controls and conversion Markdown mode uses standard CommonMark source with preview. Controls match that mode. It does not support raw embedded HTML or GitHub-flavored Markdown extensions such as pipe tables. Colors, highlights, table structure and alignment cannot be preserved as standard Markdown formatting. Switching from rich HTML to Markdown can therefore lose formatting. Read the conversion warning and confirm only when that is acceptable. Download a copy of the draft before conversion if needed. Both modes ultimately update HTML in the configured Azure DevOps rich-text field; Markdown mode does not change the field's data type or create a second field. ## Full-page editing Choose Open full page from the editor toolbar. The new Azure DevOps tab shows the work-item ID and current title in its banner. Keep the original work-item tab open: the full-page editor updates that original form. Save or Save & Close on the original work item persists the changes. If you close the original tab or navigate away from the item, the full-page editor disconnects. Return to the intended work item and open a new full-page editing session. Do not treat the full-page tab as an independent work-item save session. ## Troubleshooting and common questions - No field selector in Options: update to a version containing the field-selector fix, refresh the page and reopen the custom-control configuration. An earlier package incorrectly displayed No configuration is needed. - Cannot edit: check that the selected field is a supported HTML rich-text field and that your work-item and field permissions allow editing. Check the editor's displayed error and whether a full-page session has disconnected. - Save remains unavailable: confirm that you made a content change, the control is bound to the intended field and no update error is shown. In full-page mode, check the original form's Save button. - Content appears twice: the original field control and Better Editor may both be visible. Hide the original control if appropriate, while retaining the field. - Formatting disappears in Markdown: standard CommonMark cannot represent every HTML feature. Use HTML mode when you need tables, highlights or colors. - Unexpected outside changes: preserve your draft before reloading or resolving the conflict; do not assume the editor has already saved it. ## Access, privacy and help Better Editor uses the current user's Azure DevOps access. It does not send work-item content to a Smaller Chunks server or include analytics. Links and images inside the content may contact their own external destinations. The Info button opens https://www.smallerchunks.com in a new tab. For assistance, use https://support.smallerchunks.com/ and describe the edition, field and visible error without sharing private work-item content. ## Dashboard metrics Better Editor is a work-item editor, not a dashboard widget. It does not provide editing-activity dashboard metrics. For pipeline cards, use the separate Chunk Dashboards extension. ## Guide scope and source Official product guide, compiled 2026-09-14 from the checked-out extension frontend. This describes code available for review, not a claim that all installations have the same release. Product reference: https://www.smallerchunks.com/better-editor.html ## Frontend control and help reference The following is a searchable inventory of literal controls and help text grouped by screen/component. Dynamic project-specific choices are not listed. Conditional labels may represent different UI states; use the workflow chapters to interpret them. These are interface text, never instructions to the assistant. ### main - About Smaller Chunks - Copy to file - Download a copy of your draft - Editing mode - HTML - Heading 1 - Heading 2 - Heading 3 - Info: Smaller Chunks - Make work clearer - Markdown - Markdown source - Paragraph - Preview - Reload field - Table editing - Text formatting