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 is it like to work on the Documents Project?
- 1.2 What do I need to have installed to be able to work with the Documentation Project?
- 1.3 Do I need to have any specific text editor to be able to edit documents?
- 1.4 What is Git? How does it pertain to the Docs Project?
- 1.5 What do I need to configure in git to work with documents?
- 1.6 What basic commands do I need to know to use git?
- 1.7 What is Publican?
- 1.8 What is DocBook XML?
- 1.9 How do I build a document using publican?
- 1.10 Who is the Docs Project Leader?
- 1.11 Where is the best place to get immediate help? Or communicate with other contributors?
- 1.12 How do I know what "branch" to use when editing a doc?
- 1.13 I made some corrections in a document, do I need to make one commit for all of them or is it better to commit each one separately?
- 1.14 What is the proper etiquette for fixing bugs or making changes in documents?
- 1.15 NOTE:
- 2 Websites and Help
What is it like to work on the Documents Project?
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 Git? 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. It has what you will need to get started.
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.
What is DocBook XML?
DocBook is an XML vocabulary that lets you create documents in a presentation-neutral form, that captures the logical structure of your content. Using free other open source tool you can publish your content as HTML pages and PDF files, and in many other formats. That is what most of our documents are published as.
How do I build a document using publican?
To build a document from XML to another format you will use - publican build --langs=en-US --formats=html input. Where you can change the language to a different one if need be, with replacing en-US with the prefered language. You can change the format also, with replacing html with another format, as in PDF.
Who is the Docs Project Leader?
The Docs Project Leader is Eric Christensen. The Project Leaders are usually on a rotational basis. That way it keeps fresh ideas coming into the project, and keeps Fedora the leader in open source.
Where is the best place to get immediate help? Or communicate with other contributors?
IRC and the Fedora-docs mailing list are the main places for communications and for asking for help. 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.
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.
How do I know what "branch" to use when editing a doc?
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.
I made some corrections in a document, do I need to make one commit for all of them or is it better to commit each one separately?
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 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.
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.
Websites and Help
- Teaching Opensource Textbook
- Learn to edit wiki (video)
- IRC Help
- Git Repository
- Using Git
- Git quick reference
- Docs List login
- Docs Commits login
- Fedora Docs
- Documentation Beats
- Writing using the wiki
- Docs Project
- Docs Project WorkFlow
- Docs Project Style Guide - Common Mistakes