Others rely on the comments that Git adds to the files about the conflicts: open the file in an editor, assess the conflicts, and make a decision about which change to accept. What about conflicts, with multiple people working on the same doc? There are several ways of handling such merge conflicts.LFS also helps ensure that the large files don’t clutter up your repo. For some of those files, depending on file type, LFS can also help you see the difference between versions. Git LFS (Large File Storage) is available for uploading large files such as videos, Adobe files, etc.They also use Liquid for other conditional publishing, such as selecting enterprise docs only. For version control within the files, Jenn’s team uses Liquid syntax.It’s a good idea to be very descriptive with your commit messages, so that you can figure out which commit to roll back if necessary.Branches can be very small (just fixing a typo, for example) or very large (for a new feature).Otherwise you’ll have problems later when merging your changes back. In particular, before starting a new branch. A tip: sync with the main repo on GitHub often.Then merge back into the master branch when ready for pushing to production. Therefore, always make changes and do collaboration on a branch. GitHub views the master branch as the deployable state – so, it’s production. The team of presenters recommend against working off master, because it’s more difficult to back out changes. Jenn does not ever work off the master branch.Then eventually push to the mega branch.Then you create the pull requests off your branch, and do the reviews there.Create a mega branch, then create branches off that mega branch.Often the mega branch is for development of a doc change over a longer period of time.Sometimes she’ll have a PR with 200 changes in it. Jenn likes to make pull requests (PRs) often, so that she can get feedback quickly.Then they make their pull request on the web. They commit changes locally, then push to the web (that is, sync to the repo on GitHub).They make all the changes in the branch, and make commits often.A few people have heard of it, and Jenn’s team is talking about it too. A question came from the floor about Asciidoc.A useful tool for converting documentation from HTML to Markdown: pandoc.The source format for the documentation is Markdown.I suggested that it’d be great to have some information in the GitHub docs about best practices for managing such a branch. The term “mega branch” isn’t generally known.
But usually, Jenn just works in her own branch.
Shipit squirrel icon update#
When a fix or update is required to the documentation, the technical writers start by raising an issue in the help docs repo.Some things I gleaned about a technical writing workflow using Git and GitHub: Here’s the repository that they created during the session, to illustrate the workflow: TCCamp demo repo on GitHub. Then Jenn, a technical writer at GitHub, explained her workflow for technical writing in particular. Jamie started with an overview of the traditional GitHub workflow. Stefan Stölzle was there as technical advisor, and answered plenty of questions from attendees. The presenters were Jamie Strusz and Jenn Leaver, both from GitHub. There was a good variety of Git skill levels amongst the attendees, from people who had never used Git or GitHub, to people who were comfortable using Git on the command line. The session covered primarily workflow on, and also touched on using Git on the command line. Any inaccuracy is my mistake, not that of the presenters. A team from GitHub walked us through a workflow using Git and GitHub for technical documentation. In the morning there were a few workshops, one of which was titled “Git-based Technical Communication Workflows”. This week I attended TC Camp 2016 in Santa Clara.
0 kommentar(er)
