toggle quoted messageShow quoted text
Thank you, Chris, Alastair, and Jean-Noël for your feedback.
I do want to set some additional context here:
- I am familiar with and comfortable with Git, although it is
new to the technical writers on this project. (And perhaps
frightening to the manager.) I started using Git when the
DITA-OT project moved to it from SVN, and I'm still grateful for
all the help that Jarno Elovirta, Robert Anderson, and Roger
Sheen gave me as I learned Git.
- Yes, good practices for Git are just standard, good software
development practices: Keep feature branches discrete; update
feature branches by pulling from the current development
repository frequently; commit thoughtfully and frequently with
good commit messages, so that cherry picking is a possibility.
- For this project, the technical writers are using oXygen, and
we can control formatting through common project files to reduce
That said, version control with Git can have a steep ramp-up for
technical writers. Any thoughts about how to best minimize that?
And how to best plan a process for the scenario in which a
writer wants to merge some (but not all content) from a feature
branch into the development branch? In the absence of
granular commits with descriptive commit messages, cherry picking
is a not a realistic option.
So far I've handled this manually, by asking the writer for names
of the files that she wanted merged; merging them into a local
copy of the development branch; resolving merge conflicts and QA
errors (errors in DITA source, spelling); and eventually merging
into the development branch.
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)
On 12/18/2019 6:13 AM, Alastair Dent
Using Git requires a change in thinking.
All authors need to abandon the thoughts of 'check out',
'check in', 'lock'. Those don't really apply to git.
New concepts that are absolutely essential to learn are
'remote', 'origin', 'branch'.
When an author pulls a repository ( pulling a copy of the
main repository), they are creating a local repository. Their
work will take place in this repository. Usually, good
practice is to create a local branch for new work. *Always*
update your local repository before starting a new piece of
work (fetch and pull the latest updates from the origin).
When working on DITA files, the files are numerous and
small. It is unusual for two authors to both edit the same
file at the same time. Frequent updates and pushes are the way
This is no different to programmers working on code.