Here’s the recording of our third Documentation Office Hours from 15th March 2024:
The one where we explain the GitHub UI plus demo a few git command line tools
Our Get started with git pull request.
Lazygit: https://github.com/jesseduffield/lazygit
gitui: https://github.com/extrawurst/gitui
tig: https://github.com/jonas/tig/
00:05 Introduction and updates
02:00 Congratulations
02:45 Getting started with git guide
04:15 GitHub web UI tour
04:40 Closed issue list
05:33 View changes in a pull request
08:00 Exploring a repository
08:44 Blame, and who wrote what
10:36 Find commit messages for any line
11:40 git UI demos
14:20 Lazygit
18:23 gitui
24:47 tig
32:40 Questions and answers on git helpers
Questions
Q: Do we have to use Ubuntu Linux?
A: Not at all, and we want to actively encourage people using different Linux distributions, and different operating systems, to take part. Linux users should have the least issues, with most projects including packages for your chosen distribution. macOS users will find git easy to install, and other open source tools available through Homebrew. Windows users can use WSL to run Linux within their Windows desktop. Better than all these, however, is Multipass, which is a cross-platform system for easily launching virtual machines. It enables any of the above to run a fresh Ubuntu instance within your default environment.
Q: Do you have any guides on writing style or how to structure and format your controbutions?
We don’t yet have anything specific to the Academy, but this is something we very much want to document. For the time being, each project will typically have its own guidelines. The snap project has a page called Contribute to our documentation, for example. This covers style requirements, the kind of Markdown syntax you can use, and what other features may be supported by the documentation set. These are all very similar across our projects, but also different in small ways that means we’ve not yet been able to create a single guide we can use across everything. External projects may also want to get involved, and they may have their own requirements. These details should all be covered in the Task/Issue description.
Another resource is our Canonical Documentation Style Guide. This provides advice on which words to use and when to use them.
However, we can’t emphasise enough that structure and style guidelines are only guidelines, and while they’re important for overall consistency, they can easily be added, fixed and edited later. The most important and challenging task is always finding simple and easy ways to communicate an idea, regardless of its structure or spelling.