diff --git a/doc/bugs/Git_checkout_fails_using_--recurse-submodules.mdwn b/doc/bugs/Git_checkout_fails_using_--recurse-submodules.mdwn
index 8cd6a7c01a..2dfc6c7995 100644
--- a/doc/bugs/Git_checkout_fails_using_--recurse-submodules.mdwn
+++ b/doc/bugs/Git_checkout_fails_using_--recurse-submodules.mdwn
@@ -2,10 +2,15 @@
 
 Consider a parent repository with a single submodule and two branches in the parent repository. When checking out a branch in the parent using --recurse-submodules, git returns the error:
 
+```
 fatal: could not open 'sub/.git' for writing: Is a directory
+```
 
-This issue was originally mentioned in the post at https://git-annex.branchable.com/submodules/ where there is a statement that "The conversion of .git file to .git symlink mostly won't bother git." The original poster said there was a solution to use "git checkout mybranch && git submodule update", but this does not work with git version 2.40.0 and git-annex version 10.20230407. In this case, rather than giving a fatal error, git is unable to remove the submodule directory and leaves it untouched. However, this then leaves the new branch in a dirty state (because the submodule is an untracked or modified file). 
+This issue was originally mentioned in [this post](https://git-annex.branchable.com/submodules/) where there is a statement that "The conversion of .git file to .git symlink mostly won't bother git." It is precisely this change that git has a problem with when changing to a new branch. The original poster said there was a solution to use "git checkout mybranch && git submodule update", but this does not work with git version 2.40.0 and git-annex version 10.20230407. In this case, rather than giving a fatal error, git is unable to remove the submodule directory and leaves it untouched. However, this then leaves the new branch in a dirty state (because the submodule is an untracked or modified file). 
 
+The end goal for using `--recurse-submodules` is so that either
+  1) a submodule will exist only in a single branch and/or
+  2) different branches in the parent will automatically point to different branches in the submodule
 
 ### What steps will reproduce the problem?
 Here is a sequence of steps to reproduce the issue.
@@ -66,19 +71,12 @@ git checkout main --recurse-submodules
 ### What version of git-annex are you using? On what operating system?
 
 git version 2.40.0
+
 git-annex version: 10.20230407
+
 operating system: darwin aarch64
 
 
-### Please provide any additional information below.
-
-[[!format sh """
-# If you can, paste a complete transcript of the problem occurring here.
-# If the problem is with the git-annex assistant, paste in .git/annex/daemon.log
-
-
-# End of transcript or log.
-"""]]
 
 ### Have you had any luck using git-annex before? (Sometimes we get tired of reading bug reports all day and a lil' positive end note does wonders)
 Yes! Been familiarizing myself with it on and off over the last year and am very excited about it's possibilities.