User:Emad78/New Docs contributor FAQ dump

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

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.

Docs FAQ

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:

publican
publican-fedora
git
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

gedit
emacs
kate
vim

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. For more information also read the Git Community Book and also the Git wiki page

What do I need to configure in git to work with documents?

Here are a few commands that will get you set up. This is just the basic setup needed to work with documentation. Check out the Docs Project work using git wiki for a full follow through to using Git.

Install the git-all and publican-fedora packages with yum:

su -c 'yum install git-all publican-fedora'

Create your global git configuration:

git config --global user.name 'John Doe'
git config --global user.email 'jdoe@example.com'
git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

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 other free open source tools you can publish your content as HTML pages and PDF files, and in many other formats. The former 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 your prefered one if need be, by replacing en-US. You can change the format also, by 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.

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. For someone just starting out in the Docs Project, or any project for that matter, there might be a time when the newbie might feel like he is "bugging" experienced contributors or asking to many questions. That is not a bad thing. Everyone needs to ask questions. Here is a link to make you to make you into an instant contributor.

Turn annoying newbies into instant contributors

Websites and Help

Needs Cleanup

<Emad78> So the fedorapeople.org is where the docs go to be finalized? Is that how it works? I can see some of them in there.

kushal has quit (Ping timeout: 246 seconds)

<jjmcd> Emad78, those are drafts updated nightly for L10N <jjmcd> They are in the process of being translated <jjmcd> https://fedoraproject.org/wiki/Draft_documents_for_L10N <Emad78> jjmcd: Ok, so they translate and you build every night to check for errors. <jjmcd> Exactly <jjmcd> If you look in some languages you will see the error log

susan (~susan@c122-108-162-212.rochd4.qld.optusnet.com.au) has joined #fedora-docs

<jjmcd> e.g. http://fedorapeople.org/groups/docs/release-notes/bg-BG/ <Emad78> Ok I see, I see. So then you look at the error log and go in and fix the error? <Emad78> Yeah that's the one I looked at. <jjmcd> Well, those errors were introduced by L10N so they get to fix them <jjmcd> since en-US built OK <Emad78> Ok, so then they have till the beta to do this then. <jjmcd> yep <jjmcd> And those that aren't 100% translated or don't build don't make beta <jjmcd> Well, don't make GA. Beta rpm is done <Emad78> Got it. Cool. So who actually does the building. <Emad78> You since your the owner. <jjmcd> My old buddy cron <Emad78> Ahhh that's where that come in. <jjmcd> Yep, once you get it to work the first time, just put old cron to work every night <Emad78> That's cool. I'm liking this more and more. <Emad78> So every doc should end up in fedorapeople.org for translation when it's ready. <jjmcd> That's the idea <Emad78> Awesome, Well thanks for answering my random questions.

Search