Skip to content

Commit 808fde0

Browse files
ctalauOxygen Content Fusion
ctalau
authored and
Oxygen Content Fusion
committed
Integrate review task 'Blog Post about CF'.
2 parents 72cb602 + 9e2a347 commit 808fde0

9 files changed

+243
-0
lines changed

‎git-tech-writers/cf-commit.png

31.7 KB
Loading

‎git-tech-writers/images/apply-stash.png

26 KB
Loading

‎git-tech-writers/images/cf-workspace.png

264 KB
Loading

‎git-tech-writers/images/reset-branch-to-commit.png

31.2 KB
Loading

‎git-tech-writers/images/reset-mixed-mode.png

9.98 KB
Loading

‎git-tech-writers/images/stash-changes-menu.png

32.8 KB
Loading

‎git-tech-writers/images/stash-create-dialog.png

11.7 KB
Loading

‎git-tech-writers/tame-the-branch-chaos.dita

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
3+
<topic id="topic_cml_cpm_p2c">
4+
<title>Tame the Branch Chaos – Switch Less, Write More</title>
5+
<prolog>
6+
<author>Cristian Talau</author>
7+
<critdates>
8+
<created date="2025-03-27"/>
9+
</critdates>
10+
<metadata>
11+
<keywords>
12+
<keyword>Git workflows</keyword>
13+
<keyword>Oxygen Content Fusion</keyword>
14+
<keyword>Git branches</keyword>
15+
</keywords>
16+
</metadata>
17+
</prolog>
18+
<body>
19+
<p>You’re mid-sentence, deep in the flow of writing. Then a Slack ping: “Can you quickly
20+
check something on the release notes branch?” You sigh. Time to stash your changes,
21+
switch branches, rebuild context—and just like that, your momentum is gone.</p>
22+
<p>For technical writers, this isn't a rare disruption. It’s daily reality. Between juggling
23+
multiple documentation tasks, waiting for SME feedback, and jumping between feature
24+
branches, staying focused becomes a luxury.</p>
25+
<section id="section_vkz_jqr_52c">
26+
<title>The Multi-Tasking Writer’s Dilemma</title>
27+
<p>In an ideal world, a technical writer picks up a task, finishes it in a focused work
28+
session, and moves on to the next. In reality? Writing often happens in fragmented
29+
windows between SME replies, engineering changes, and shifting priorities.</p>
30+
<p>This leads to a juggling act between:</p>
31+
<ul id="ul_ykz_jqr_52c">
32+
<li><b>Multiple feature branches</b> for in-progress tasks at different stages of
33+
completion.</li>
34+
<li><b>Quick hotfixes or urgent edits</b> that need to go out <i>now</i>.</li>
35+
<li><b>Reviews and feedback</b> that come in late, requiring you to revisit a branch
36+
you last touched two weeks ago.</li>
37+
</ul>
38+
<p>Context switching happens not just between topics, but between Git branches, editor
39+
states, and mental models.</p>
40+
<p>Each time you need to switch branches, you face a decision tree:</p>
41+
<ul id="ul_alz_jqr_52c">
42+
<li>Do you commit half-finished work?</li>
43+
<li>Do you stash and risk conflicts later?</li>
44+
<li>Do you clone the whole repository again into another folder?</li>
45+
</ul>
46+
<p>This constant overhead takes a toll: it interrupts focus, slows down delivery, and
47+
makes a high-cognitive-load job even harder. Writers end up spending more time
48+
managing branches than actually writing.</p>
49+
</section>
50+
<section id="section_blz_jqr_52c">
51+
<title>Four Ways to Juggle Branches</title>
52+
<p>When you're deep in documentation work and need to temporarily switch to another
53+
branch, you have a few options. Some are more elegant than others—but each comes
54+
with its own trade-offs.</p>
55+
<p>Let’s walk through the most common approaches, what they involve, and where things
56+
can go wrong.</p>
57+
</section>
58+
<section id="section_clz_jqr_52c">
59+
<title>The Git Stash Dance</title>
60+
<p>Stash your current changes, switch to the other branch, then come back and re-apply
61+
the stash.</p>
62+
<p><b>Workflow in Oxygen:</b></p>
63+
<ol id="ol_jlz_jqr_52c">
64+
<li>Stash your local changes<ol id="ol_dpz_csr_52c">
65+
<li>If you haven't already, install the <xref
66+
href="https://www.oxygenxml.com/doc/ug-addons/topics/git-addon.html"
67+
format="html" scope="external">Oxygen Git Client Add-on</xref></li>
68+
<li>In the <uicontrol>Git Staging</uicontrol> view, open the triple dots
69+
menu and choose <uicontrol>Stash changes</uicontrol><p><image
70+
href="images/stash-changes-menu.png" id="image_arf_yrr_52c"
71+
width="300px"/></p></li>
72+
<li><image href="images/stash-create-dialog.png" id="image_ikn_csr_52c"
73+
width="300px"/></li>
74+
</ol></li>
75+
<li>Switch the branch</li>
76+
<li>Make quick edits, commit or push as needed</li>
77+
<li>Switch back to the original branch</li>
78+
<li>Apply the stash<ol id="ol_vhj_lsr_52c">
79+
<li>In the <uicontrol>Git Staging</uicontrol> view, open the triple dots
80+
menu and choose <uicontrol>List changes</uicontrol></li>
81+
<li><image href="images/apply-stash.png" id="image_ajn_ssr_52c"
82+
width="300px"/></li>
83+
</ol></li>
84+
</ol>
85+
<p><b>CLI workflow</b></p>
86+
<p>If you are a script passionate, you can use these commands to achieve the same result
87+
as the workflow
88+
above:<codeblock id="codeblock_fll_mjs_52c" outputclass="language-bourne">git stash push -u -m "WIP on 'master' - taming the branch chaous [27 Mar 2025]"
89+
git checkout release-notes-branch
90+
# Make quick edits, commit or push as needed
91+
git checkout master
92+
git stash pop</codeblock></p>
93+
<p>
94+
<note id="note_ens_wsr_52c" type="tip">
95+
<ul id="ul_nlz_jqr_52c">
96+
<li>Make sure to leave the "Include untracked files" checkbox on, as it is
97+
by default. Otherwise, some newly added files may not be included in the
98+
stash.</li>
99+
<li>Always preview stashes before applying.</li>
100+
<li>Include the branch name in the stash name. This way, you avoid applying
101+
the stash on the wrong branch.</li>
102+
<li>Include the data in the stash name. This way you can cleanup old stashes
103+
with confidence.</li>
104+
</ul>
105+
</note>
106+
</p>
107+
</section>
108+
<section id="section_olz_jqr_52c">
109+
<title>Temporary WIP Commit</title>
110+
<p>Quickly commit your in-progress work to get it out of the way.</p>
111+
<p><b>Oxygen Workflow</b></p>
112+
<ol id="ol_plz_jqr_52c">
113+
<li>Stage and commit all the local changes</li>
114+
<li>Switch the branch</li>
115+
<li>Make quick edits, commit or push as needed</li>
116+
<li>Switch back to the original branch</li>
117+
<li>Open the <xref
118+
href="https://www.oxygenxml.com/doc/ug-addons/topics/git-addon.html#git-addon__section_hjy_kmy_kpb"
119+
format="html" scope="external">history view</xref> &amp; filter commits by
120+
"Current local branch"<ol id="ol_lzj_h5r_52c">
121+
<li><image href="images/reset-branch-to-commit.png" id="image_cfx_g5r_52c"
122+
width="300px"/></li>
123+
</ol></li>
124+
<li>Reset branch to the parent commit with "mixed mode"<ol id="ol_g25_h5r_52c">
125+
<li><image href="images/reset-mixed-mode.png" id="image_wzz_j5r_52c"
126+
width="300px"/></li>
127+
</ol></li>
128+
</ol>
129+
<p><b>CLI workflow</b><codeblock id="codeblock_lhf_kjs_52c">git add .
130+
git commit -m "WIP: halfway done with config docs"
131+
git checkout release-notes-branch
132+
# Do your other work
133+
git checkout master
134+
git reset HEAD~1 --mixed</codeblock></p>
135+
<p>
136+
<note id="note_mn2_ysr_52c" type="tip">
137+
<ul>
138+
<li>If working with others on the same branch, do not push! Your local
139+
commits may affect rebases or create confusion.</li>
140+
<li>When undoing the commit, make sure you have the "mixed" option
141+
checked.</li>
142+
</ul>
143+
</note>
144+
</p>
145+
</section>
146+
<section id="section_rlz_jqr_52c">
147+
<title>Checkout in a Separate Folder </title>
148+
<p>Create another working directory with a separate clone. This approach is simple to
149+
understand but is heavy - you duplicate the entire repository and is not uncommon
150+
for companies to have multi-gigabyte repositories.</p>
151+
<p>As a mitigation, Git introduced the <codeph>worktree</codeph> command which allows
152+
you to reuse the <codeph>.git</codeph> folder between multiple working copies. For
153+
example, the working copy of the Oxygen's user guide has ~250MB and the
154+
<codeph>.git</codeph> folder is ~200MB of them.</p>
155+
<p>To use this feature you need to go to the terminal and work with these commands:</p>
156+
<codeblock id="codeblock_emz_jqr_52c" outputclass="language-bourne"># From your repo root
157+
git worktree add ../release-notes release-notes-branch
158+
cd ../release-notes
159+
# Make your changes and commit them
160+
cd ../my-main-repo
161+
</codeblock>
162+
<p>
163+
<note id="note_tfm_dtr_52c" type="tip"><codeph>worktree</codeph>s are fantastic for
164+
long-lived parallel work. Just don't forget where each copy lives and to remove
165+
them once you are done: <codeph id="codeblock_fmz_jqr_52c">git worktree remove
166+
../release-notes</codeph>. </note>
167+
</p>
168+
</section>
169+
<section id="section_gmz_jqr_52c">
170+
<title>Oxygen Content Fusion Workspaces</title>
171+
<p><xref href="https://www.oxygenxml.com/content_fusion.html" format="html"
172+
scope="external">Oxygen Content Fusion</xref> is a <b>web-based Git-enabled DITA
173+
CMS</b> providing structured content authoring, AI-assisted refinement via
174+
Oxygen AI Positron, and publishing.</p>
175+
<p>One of its benefits for author is that you can create multiple lightweight authoring
176+
<xref
177+
href="https://www.oxygenxml.com/doc/versions/8.0/ug-content-fusion/topics/cf-projects-workspace.html"
178+
format="html" scope="external">workspaces</xref> in your browser, for <i>any</i>
179+
branch, and switch between them by just switching browser tabs. Unlike multiple
180+
checkouts, workspaces don’t duplicate files. They’re created instantly without
181+
copying any content, and with minimal overhead.</p>
182+
<p><b>Workflow in CF:</b></p>
183+
<ol id="ol_hmz_jqr_52c">
184+
<li>Stay on your current task in your authoring tool.</li>
185+
<li>In Content Fusion, select a different branch to create a new workspace.<ol
186+
id="ol_rgs_bvr_52c">
187+
<li><image href="images/cf-workspace.png" id="image_nm1_svr_52c"
188+
width="300px"/></li>
189+
</ol></li>
190+
<li>Edit or review content independently from your current Git state.</li>
191+
<li>Commit changes when you are ready<ol id="ol_md3_wvr_52c">
192+
<li><image href="cf-commit.png" id="image_er3_fbs_52c" width="300px"/></li>
193+
</ol></li>
194+
<li>... or just leave the changes there, and switch to some more urgent work</li>
195+
</ol>
196+
<p>
197+
<note id="note_arg_2tr_52c" type="tip">Need more feedback from a SME? Just create a
198+
<xref
199+
href="https://www.oxygenxml.com/doc/versions/8.0/ug-content-fusion/topics/content_fusion_task_details-x2.html"
200+
format="html" scope="external">review task</xref> from your workspace and
201+
set a due date. Content Fusion will automatically remind the SME—so you don’t
202+
have to chase them for a response.</note>
203+
</p>
204+
</section>
205+
<section id="section_imz_jqr_52c">
206+
<title>How Do <i>You</i> Handle Branch Chaos?</title>
207+
<p>Every technical writer has their own way of dealing with the Git shuffle. Maybe
208+
you’re a <codeph>stash</codeph> master. Maybe you keep six cloned repositories open
209+
at all times (no judgment). Or maybe you’ve found a completely different workflow
210+
that works for your team.</p>
211+
<p>We’d love to hear from you:</p>
212+
<ul id="ul_ymz_jqr_52c">
213+
<li>Which approach saves you the most time?</li>
214+
<li>Have you tried Git <codeph>worktree</codeph>s or Content Fusion workspaces?</li>
215+
<li>What’s the weirdest branch-juggling ritual you’ve developed?</li>
216+
</ul>
217+
<p>
218+
<note id="note_ehs_ftr_52c" type="important"><b>Share your tips, tricks, or horror
219+
stories in the comments—or reach out to us directly.</b> We’re always
220+
looking to learn from real-world workflows and improve the tools writers rely on
221+
every day.</note>
222+
</p>
223+
</section>
224+
</body>
225+
<related-links>
226+
<link
227+
href="https://www.oxygenxml.com/events/2025/webinar_solving_common_git_and_dita_challenges.html"
228+
format="html" scope="external">
229+
<linktext>Webinar: Solving Common Git and DITA Challenges</linktext>
230+
</link>
231+
<link href="https://www.youtube.com/watch?v=mzYjlPP1MxQ" format="html" scope="external">
232+
<linktext>XML Based Docs As Code – Combining DITA XML With GitHub and Continuous
233+
Delivery</linktext>
234+
</link>
235+
<link
236+
href="https://www.oxygenxml.com/events/2020/webinar_documentation_management_inspired_by_software_development.html"
237+
format="html" scope="external">
238+
<linktext>Webinar- Docs as Code: Documentation Management Inspired by Software
239+
Development</linktext>
240+
</link>
241+
</related-links>
242+
</topic>

‎git-tech-writers/using_git_for_technical_writing.ditamap

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,6 @@
2020
<topicref href="handling_translations.dita"/>
2121
<topicref href="sharing_common_settings.dita"/>
2222
<topicref href="publishing_content_from_git.dita"/>
23+
<topicref href="tame-the-branch-chaos.dita"/>
2324
</topicref>
2425
</map>

0 commit comments

Comments
 (0)