====== DokuWiki Help Authoring Guide - Visual Editor ======

===== Scope and Outcome =====

This guide trains an editor to create a new help article, maintain existing content, and manage revisions using the Visual Editor. All screenshot placeholders are intentionally detailed for downstream arrow/box/stamp annotation.
Output standards required by this guide:
  * Single H1 per article.
  * Clear heading hierarchy (H2/H3/H4) with no decorative heading misuse.
  * Step lists remain continuous without accidental restart.
  * Images are attached to the step line intent and context.
  * Related Topics uses one internal link per line and no duplicate targets.
  * Every significant save includes a revision summary.

===== Access, Permissions, and Pre-Checks =====

  - Sign in with an account that has edit permissions for the target namespace. \\ [[visual_precheck_001.png:Browser on DokuWiki login page with username field, password field, and sign-in button. Add arrow to currently active user profile indicator after login.]]
  - Open the destination article or a nearby article in the same namespace to confirm visibility of the Page Tools menu. \\ [[visual_precheck_002.png:Article view with Page Tools panel visible. Highlight both article title area and page-tools area.]]
  - Confirm the Create Page tool is visible in Page Tools. \\ [[visual_precheck_003.png:Page Tools expanded, with Create Page entry boxed and arrow stamp indicating where to click.]]
  - Confirm you can open Visual Edit mode from the current page. \\ [[visual_precheck_004.png:Edit controls showing Visual Edit option. Include pointer over the Visual mode selector.]]
  - If the page is locked by another editor, wait or coordinate before proceeding. \\ [[visual_precheck_005.png:Lock notice/banner visible. Box lock message text and include callout of lock owner/timestamp if shown.]]

===== Create a New Help Article (Visual Editor Path) =====

Use the Create Page tool so page ID, heading, sidebar placement, and editor mode are configured in one flow. This prevents orphan pages and reduces post-save navigation fixes.
  - From the source or parent article, click Create Page in Page Tools. \\ [[visual_create_006.png:Page view with Create Page tool highlighted. Include a red box around Create Page and an arrow from upper-right pointing down.]]
  - In Sidebar Location, choose the exact navigation node where the new article belongs. \\ [[visual_create_007.png:Create Page dialog with sidebar tree expanded. Box the selected node and show sibling nodes for context.]]
  - Set Placement Relative to Selected Section (Nested, Before, or After) based on navigation intent. \\ [[visual_create_008.png:Insert mode dropdown open showing Nested/Before/After. Add annotation describing selection rationale.]]
  - If required, enter New Subnamespace Path for deeper categorization. \\ [[visual_create_009.png:Subnamespace input box focused with sample value like setup:requiredsetupsteps. Highlight colon-separated format.]]
  - Enter Page ID using lowercase, underscores where needed, and no spaces. \\ [[visual_create_010.png:Page ID field with valid and invalid examples side-by-side annotation.]]
  - Enter Page Title (H1 heading) exactly as the human-facing article name. \\ [[visual_create_011.png:Page Title field with final title text selected. Box this field and call out 'controls article H1'.]]
  - Optionally set Sidebar Menu Label only when it must differ from title for navigation readability. \\ [[visual_create_012.png:Sidebar label field with note showing when left blank it defaults from title.]]
  - Choose Open New Page in Editor = Visual Edit (WYSIWYG). \\ [[visual_create_013.png:Editor mode dropdown open with Visual Edit selected and DW Edit option visible below.]]
  - Leave Insert/Update in Sidebar checked unless creating a hidden or temporary page. \\ [[visual_create_014.png:Checkbox row showing add-to-sidebar option checked. Add callout about standard behavior.]]
  - If your workflow uses context redirects, toggle Generate Context ID; otherwise leave it off. \\ [[visual_create_015.png:Generate context ID checkbox and helper text visible. Highlight optional nature.]]
  - Click Create Page. \\ [[visual_create_016.png:Create button pressed state with spinner/loading indicator if present.]]
  - Verify immediate redirect to the new article in Visual Edit mode. \\ [[visual_create_017.png:New blank article opened in visual editor with title bar and editable body area boxed.]]

===== Build Article Structure in Visual Editor =====

  - Insert one H1 only at top (already created by Create Page flow); do not add a second H1. \\ [[visual_structure_018.png:Visual editor content area showing title and heading style dropdown. Box H1 control and current heading.]]
  - Create H2 sections for major procedures and H3/H4 for subsections. \\ [[visual_structure_019.png:Heading dropdown expanded with Heading 2/3/4 options and sample selected paragraph.]]
  - Draft a short purpose statement below H1 before procedural steps. \\ [[visual_structure_020.png:Top paragraph under title with sentence-level box and annotation for expected length (1-3 lines).]]
  - Use numbered lists for sequence-critical tasks. \\ [[visual_structure_021.png:Numbered list toolbar button highlighted and first two steps visible in body.]]
  - Use bullet lists only for non-sequential options/details. \\ [[visual_structure_022.png:Bulleted list under a numbered step rendered as nested details. Box indentation controls.]]
  - Avoid blank paragraphs inside a numbered workflow to prevent visual ambiguity. \\ [[visual_structure_023.png:Cursor shown between list steps where blank line is not allowed; warning annotation included.]]
  - For in-step callouts, keep explanatory note attached to the step content rather than separate heading blocks. \\ [[visual_structure_024.png:A numbered step with inline note sentence. Arrow pointing to attached callout text region.]]

===== Use Visual Formatting Features Correctly =====

  - Apply Bold only to UI labels, key actions, and critical warnings. \\ [[visual_format_025.png:Text selection with bold button active. Box both selected words and toolbar bold icon.]]
  - Use Italic sparingly for emphasis, not for normal procedural text. \\ [[visual_format_026.png:Italic toggle in toolbar with sample phrase and annotation on limited use.]]
  - Use underline only when your style guide explicitly calls for it. \\ [[visual_format_027.png:Underline button visible but callout warns against overuse.]]
  - Use strikethrough only for deprecated paths or historical references. \\ [[visual_format_028.png:Strikethrough example line with annotation 'deprecated path only'.]]
  - Use undo/redo immediately when format drift appears. \\ [[visual_format_029.png:Undo/redo controls boxed with before/after mini callouts in content area.]]
  - Use remove-format or clear-style tools when pasted content brings unwanted styles. \\ [[visual_format_030.png:Pasted paragraph with mixed styling and clear-format action highlighted.]]
  - Insert horizontal rules only between major sections, not between every step group. \\ [[visual_format_031.png:Horizontal line in editor with annotation for proper placement.]]
  - Use tables for matrix/reference data, not linear task procedures. \\ [[visual_format_032.png:Table insert menu and sample 3-column reference table in article body.]]

===== Add Links, Internal Cross-References, and Related Topics =====

  - Use internal links for same-wiki articles whenever possible. \\ [[visual_links_033.png:Link dialog showing internal page selection/search with target article chosen.]]
  - When linking to a specific section, verify anchor resolves after save. \\ [[visual_links_034.png:Link dialog anchor field filled and preview of target section shown.]]
  - Use external links only for authoritative outside destinations. \\ [[visual_links_035.png:External URL field with protocol visible and note about verified domains.]]
  - At the end of the article, create the heading exactly as ==== Related Topics ====. \\ [[visual_links_036.png:End-of-article view with Related Topics heading typed exactly and boxed.]]
  - Under Related Topics, place one internal wiki link per line. \\ [[visual_links_037.png:Related Topics list area showing clean one-link-per-line block.]]
  - Do not duplicate the same page target with two variants. \\ [[visual_links_038.png:Comparison callout showing bad duplicate pair vs good single link format.]]
  - Do not use bold labels inside Related Topics links unless explicitly required. \\ [[visual_links_039.png:Example corrected from (page|**Label**) to (page) with annotation.]]

===== Insert and Manage Images (Visual Workflow) =====

  - Place cursor exactly where the screenshot belongs in step context before inserting media. \\ [[visual_images_040.png:Cursor indicator directly inside numbered step line where image should attach.]]
  - Open Media Manager/Insert Image from toolbar. \\ [[visual_images_041.png:Media manager modal open with toolbar insert-image button highlighted.]]
  - Select the correct namespace folder matching article scope. \\ [[visual_images_042.png:Media tree on left with target namespace highlighted and sibling folders visible.]]
  - Upload or choose existing image with a clear, stable filename. \\ [[visual_images_043.png:Upload area showing file picker plus selected filename with naming convention callout.]]
  - Set image size intentionally for readability (avoid tiny/blurry output). \\ [[visual_images_044.png:Image settings dialog with width parameter field boxed and preview panel visible.]]
  - Add descriptive alt/caption text where applicable. \\ [[visual_images_045.png:Caption or alt-text field filled with explicit UI description.]]
  - After insertion, ensure image remains attached to relevant step text. \\ [[visual_images_046.png:Rendered step line with image positioned and annotation arrow connecting text and image.]]
  - Avoid remote hotlinked images for long-term reliability. \\ [[visual_images_047.png:Example of external URL image source crossed out, local media link boxed as preferred.]]

===== Edit Existing Articles in Visual Editor =====

  - Open the target article and switch to Visual Edit mode. \\ [[visual_edit_048.png:Article read view and transition to visual mode shown with mode selector boxed.]]
  - Read the full article once before editing to identify structure and cross-link dependencies. \\ [[visual_edit_049.png:Scrollable article with markers on key sections to review before change.]]
  - Locate the exact section to modify and keep heading hierarchy unchanged unless requested. \\ [[visual_edit_050.png:Section heading and subsection relationship boxed with hierarchy callout.]]
  - Apply text changes in small coherent chunks and re-check formatting after each chunk. \\ [[visual_edit_051.png:Edited paragraph with nearby unchanged paragraph for comparison.]]
  - When modifying step procedures, verify numbered sequence continuity from start to finish. \\ [[visual_edit_052.png:Long numbered list with no resets; arrows show list progression.]]
  - If adding new screenshots, insert them at the precise step and update surrounding wording. \\ [[visual_edit_053.png:Before/after step comparison with new image insertion location boxed.]]
  - Update Related Topics only when scope changes or new sibling articles are relevant. \\ [[visual_edit_054.png:Related Topics section with one new link added and duplicate removed.]]

===== Save, Summaries, Preview, and Quality Checks =====

  - Use Preview before final save when touching list structures, headings, or images. \\ [[visual_save_055.png:Preview pane and editor pane split with changed region highlighted.]]
  - Enter a revision summary describing what changed and why. \\ [[visual_save_056.png:Summary field near save controls filled with concise but specific summary text.]]
  - Save the page and wait for full render. \\ [[visual_save_057.png:Save button pressed and post-save rendered page visible.]]
  - Re-open the article in read mode and verify: headings, list continuity, images, links, and related topics. \\ [[visual_save_058.png:Published article with QA checklist callouts around each validation area.]]
  - Open at least two related linked pages to confirm no broken navigation. \\ [[visual_save_059.png:Two browser tabs with linked pages loaded and status checks annotated.]]

===== Revision History, Compare, and Restore =====

  - Open Revisions for the article from page tools. \\ [[visual_revision_060.png:Revisions entry in page tools boxed and clicked.]]
  - Select two revisions and run a side-by-side diff. \\ [[visual_revision_061.png:Diff screen with added/removed content colors boxed and legend highlighted.]]
  - Verify whether a regression was introduced (list resets, wrong heading levels, bad links). \\ [[visual_revision_062.png:Diff view callouts pinpointing formatting regressions.]]
  - Restore a prior revision only after confirming it resolves the issue and does not drop valid updates. \\ [[visual_revision_063.png:Restore confirmation control and warning text highlighted.]]
  - After restore, add a new revision summary documenting why rollback was done. \\ [[visual_revision_064.png:Post-restore edit summary with rationale text entered.]]

===== Visual Editor Feature Checklist =====

  * Heading levels (H2/H3/H4), paragraph style, bold/italic/underline/strike.
  * Numbered and bulleted lists, nesting controls, indent/outdent.
  * Internal/external links, anchor links, unlink/edit-link.
  * Media manager insert, image sizing, caption/alt text.
  * Table insert/edit, row/column add/remove, alignment.
  * Horizontal rule, special characters, clear formatting.
  * Undo/redo, preview, save summary, revisions compare/restore.

===== Screenshot Capture Instructions for Annotation Tool =====

  - Capture full-page context first, then tight crop around the exact control used in each step. \\ [[visual_capture_065.png:Example split: full context screenshot and detail crop screenshot with matching IDs.]]
  - Keep cursor visible when instruction references precise placement. \\ [[visual_capture_066.png:Cursor positioned in text line where image insertion or edit happens.]]
  - Leave enough whitespace around dialogs for callout boxes and arrow labels. \\ [[visual_capture_067.png:Dialog screenshot with margin guides drawn to show annotation-safe area.]]
  - Use consistent resolution and zoom so arrow positions remain predictable across steps. \\ [[visual_capture_068.png:Browser zoom indicator and image dimensions panel shown with approved setting.]]
  - Name screenshots to match placeholder IDs exactly for automated substitution. \\ [[visual_capture_069.png:Folder listing where filenames match placeholder tokens one-to-one.]]

==== Related Topics ====
[[documentation:help_article_authoring_visual_editor]]
[[documentation:help_article_authoring_dwedit_wiki_markup]]