This document is for anyone wanting to provide contributions to the Documentation Project. These are some of the most frequent questions asked by a new contributor. This document will not answer all of the questions you may have, but it will get you the basic ideas of what is needed to start helping out with the Docs Project.
- 1 Docs FAQ
- 1.1 What do I need to have installed to be able to work with the Documentation Project?
- 1.2 Do I need to have any specific text editor to be able to edit documents?
- 1.3 What is this "git" I keep hearing about? How does it pertain to the Docs Project?
- 1.4 What do I need to configure in git to work with documents?
- 1.5 What basic commands do I need to know to use git?
- 1.6 What is Publican?
- 1.7 How do I build a document using publican?
- 1.8 Who is the Docs Project Leader?
- 1.9 Where is the best place to get immediate help?
- 1.10 How do I know what "branch" to use when editing a doc? Will someone tell me exactly which one to use?
- 1.11 Also can I just follow the git wiki commands to do that stuff?
- 1.12 Ok, so when I made all those edits on the UG, I made a bunch of changes in 4 files. Is it good to do so many changes and do one commit for all of them?
- 1.13 What is the proper etiquette for fixing bugs or making changes in documents?
- 1.14 What is the best way to communicate with other contributors?
- 2 Helpful Reading
- 3 Websites and Help
What do I need to have installed to be able to work with the Documentation Project?
You will not need to have a lot of applications installed. All you need to work on documents are:
- Your favorite text editor
Do I need to have any specific text editor to be able to edit documents?
No, you do not have to have a specific text editor. People use many different editors. Some of the most commonly used ones are
What is this "git" I keep hearing about? How does it pertain to the Docs Project?
Git is a revision control system. It's emphasis is on being fast and efficient. It is a working directory and full-fledged repository. It is used for keeping track of history and full revision tracking. This is where all the documents are located for the Fedora Project. To learn how to use git on the Docs Project see also Docs_Project_work_using_git. You can also read the Git Community Guide from the git project here
What do I need to configure in git to work with documents?
Read this wiki page from the Docs Project on using git, Docs_Project_work_using_git.
What basic commands do I need to know to use git?
These are the four commands that will get you working with the Docs Project:
- git clone
Creates a copy of the git repository on your computer.
- git add
Tells git that it should pay attention to a file you have changed or added.
- git commit
Tells git that you are serious about the group of changes you have "added". You need to provide a description of your change. Unlike other version control systems, git lets you commit a group of files at one time, which normally is more meaningful.
- git push
Pushes your local commits to the big repository in the sky. You need to be part of the commit group for the repository to do this.
What is Publican?
Publican is a DocBook publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, publican works to ensure your XML is up to publishable standard.
How do I build a document using publican?
Who is the Docs Project Leader?
The Docs Project Leader is Eric Christensen
Where is the best place to get immediate help?
The best place to ask for help is on the Docs Project mailing list, or on IRC. The channel for the Docs Project is #fedora-docs. There are usually plenty of people on the IRC just idle. So someone will usually pick up on you if you ask a question.
How do I know what "branch" to use when editing a doc? Will someone tell me exactly which one to use?
Here's the basic idea: If the bug is filed against a specific version of a document that ties to a specific version of software, so the bug is only applicable to that version of the document, then we want to fix the bug in the branch associated with that version. Typically that branch is "F-12" or some such. However, in docs it's common that the bug needs fixing in all versions, so that might mean fixing it in HEAD and then committing the same change in the other branches, also, we don't support (fix) docs that are tied to a release of Fedora that is no longer supported.
Also can I just follow the git wiki commands to do that stuff?
The git guide on the wiki has most of the commands you need, I think.
Ok, so when I made all those edits on the UG, I made a bunch of changes in 4 files. Is it good to do so many changes and do one commit for all of them?
Are they all a fix for one bug report? if so, one commit is fine. One per bug report is a good measure, another example of where to split: if you make big structure changes, do those first and commit, then do content changes (clean-up, typos, etc.) as a second commit, it makes it easier for others to review the work and see the impact. One nice thing about git, if you haven't discovered it, is that committing is easy since it's a local event; I find myself committing more often for more granular reasons because it's "cheap" and can be done offline.
What is the proper etiquette for fixing bugs or making changes in documents?
You can put a note in the bug report that you'd like to fix it, or go ahead and show the fix. If you've been given commit rights to the doc repository by the doc owner you have already been given what you need to make your own decision - if you think you have it (or even may have it), do the fix and commit it. you can note in the bug report that you made a commit (link) and think it fixes the bug., if so, please close. of course, if you keep doing that, you'll end up with bugs assigned to you :) remember -- source control management means never having to say you are sorry, if your fix doesn't work, it can be backed out, or more likely, just tweaked in the next commit.
=== Can two people work on the same document? Will there be any conflicts with more than one person commiting changes at the same time?
That is almost impossible, it's all in git, and git pretty cleanly resolves differences. So with that said, if there are lots of things to work on in a document. The owner will usually make a list and break it down within chapters so more than one person can help. So if your helping you can claim your "todo" and hopefully not duplicate or step on other peoples toes.
What is the best way to communicate with other contributors?
IRC and the Fedora-docs mailing list are the main places for communications. One nice thing about IRC is the asynchronous nature of it, you can leave your client running all the time, so if someone asks a question or comments, you can see it later and reply. We have discussions that span timezones and never even be together in the channel at the same time.
But also in the mailing list many more get to read advice from others; but it can be inconvenient for every little thing. Either way don't be afraid to leave questions in the channel or the mailing list and see who answers. We are "just like" coding projects, even non-docs team participants might know the right answer, etc.
NOTE: There's a cultural thing in FLOSS about "annoying newbies", both from the perspective of the experienced contributor and the person who may feel like an annoying newbie! Feel free to read the below links and learn more.