User:Emad78/New Docs contributor FAQ dump: Difference between revisions

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 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 preferred 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. For more information see also the Publican wiki Here.

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?

If they are all a fix for one particular bug then yes one commit is fine. If you are doing major changes or more than one bug fix, then doing more than one commit is good practice so others can see your work easier. An 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; People find themselves 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.

<ke4qqq> Emad78: yes <Emad78> ke4qqq: I screwed it up. <ke4qqq> how is that?? I doubt that - what can I do to help <Emad78> ke4qqq: I sent you another email. The boot your computer from the dvd is gone. And I removed my local copy. <Emad78> How do we go back. <ke4qqq> give me a second - I'll add the old version to the current repo <Emad78> Ok, <ke4qqq> Emad78: if you run git pull you should get an update and the file - but the content of the file has reverted (I went ahead and changed the name) <Emad78> So it's just git pull ssh://........... The same thing as clone? <ke4qqq> no just git pull from within the directory <ke4qqq> no need for an url - after the clone it remembers the url <Emad78> Ok I'll give it a shot. <ke4qqq> you should only need to clone the first time you access a repository.....after that git pull and git push should take care of the majority of transasctions - occasionally I find myself needing to do a reset or rebase, but those are rare. <Emad78> So when I do this. Could I do just a git clone again. Or does pull just do the file its missing? But pulling is what makes Git so fast? right? <ke4qqq> pull will get you to the same point as cloning will at this point <ke4qqq> but less work <ke4qqq> and less bandwidth <Emad78> Ok cool. Sorry for slowing you down. <ke4qqq> you could do a git clone, but git clone wipes out any local uncommitted changes - while it won't do that with git pull, generally speaking <ke4qqq> you aren't slowing me down at all <Emad78> So this is what is great about Git huh. <Emad78> So when a new guy comes in and delete a bunch of stuff. :) <Emad78> On accident that is!!! <ke4qqq> git has a lot of benefits, and I guess that's one of them. Thats one reason I say you can't cause trouble/problems. :) almost as easy as the wiki to revert changes <ke4qqq> so edit boldly, make changes boldly <Emad78> Ok, I like that. That makes it alot easier knowing that for someone starting out. This was definitely a learning experience. Thanks a bunch for helping. <ke4qqq> yes - and sadly, the only real way to learn is to scrape your knees occasionally, and just do it. but you tend to learn fast that way I think. It certainly caused me to learn fast (though I am still a git dummy) <Emad78> I totally agree with just jumping in and learning. But I'm am still hesitant for some reason. Maybe cause I'm not a young guy anymore and can appreciate what everyone does for this project. <ke4qqq> yeah, but really, it's hard to mess things up, so don't worry about that. everyone here has had to revert, or undo something. none of us are perfect, and thankfully the tools make things pretty forgiving. <Emad78> Ok, I'll keep this conversation for later looking to build confidence. <Emad78> I have a question about the Fedora &PRODVER; Were we going to change all those sections in the guides for helping the translation guys. <ke4qqq> yeah I have seen conversations around that - sadly I can't tell you what the decisions has been - rudi or jjmcd, or perhaps quaid might be good source. <Emad78> Ok, I made the changes again. So git add and the file name? <ke4qqq> if you did git pull and the file appeared you shouldn't need to git add <ke4qqq> I did the git add on my side earlier <Emad78> I cloned again. <ke4qqq> so if you cloned the file was there? <Emad78> I got ahead of myself. <Emad78> Yes it was there. <ke4qqq> you don't need to git add then <ke4qqq> only if you are adding (or changing the name) of a file <ke4qqq> I added the file earlier <Emad78> That's right and you changed the name. <ke4qqq> so it should be ok <ke4qqq> just git commit <jjmcd> git status tells you where you are on adds/commits <ke4qqq> and then git push

r> the vision is also an organized wiki, but i can take care of that one. ;) <ianweller> pages need to be organized in a series of categories <ianweller> pages need to be moved to better titles -- no CamelCase or Sub/Pages, just "Page titles with spaces and actual English" <ianweller> (subpages are useful in some cases though so don't go moving all of those) <ianweller> ((like under User: pages) <ianweller> ) <ardchoille> ianweller: How do we delete a page? Is that something only a sysop can do or is there a keyword we can use to tag a page for deletion? <ianweller> delete{{}} at the top <ianweller> and i'll take care of it eventually <ianweller> also move it to the archive: namespace <ardchoille> ok <ianweller> by way of the move tab, and just addign 'Archive:' to the beginning of teh page name <ianweller> i like typos apparently

<quaid> Emad78: that's a great idea <quaid> it's top of the list on the 0.9 planning notes <quaid> Emad78: did you see my post about that on tos@ list? <quaid> Emad78: let's talk about glossary for a moment though ... <Emad78> Yes I did, that's part of where I started from. Then I notice you wanted to add this to 0.9 and thought I could get some in there. <Emad78> Ok, what are your thoughts <quaid> want to make sure we understand how this is going to interact with the XML. <quaid> are you familiar with the <glossary> and related tags in DocBook XML? <Emad78> Ok, makes sense <Emad78> No, but I can take a look and learn. <quaid> here's the basic idea <quaid> in the course of writing a chapter, if you put in a new or glossary term, you tag the term like this: <quaid> <glossterm>some term</glossterm> <quaid> then you create a stand-alone XML file that is a <glossary> <quaid> and it has (iirc) <glossdef> definition sections <quaid> in those definition sections is where we write the actual definition <quaid> so it's one file we maintain, in the end, and each chapter writer links by doing the <glossterm> inline <quaid> DocBook when building does all the link creation, formatting of text, etc. <quaid> how this relates back to the wiki where we do actual writing is ... <quaid> I think we want to only work in the Glossary page (or whatever its name is) <quaid> (which I think you meant anyway, but I wanted to give the big picture of Why) <quaid> Mel did some work finding terms that needed explaining in any chapter, and I think she was marking them in the wiki text <quaid> e.g. some term would then translate to <glossterm>some term</glossterm> after we manually convert <Emad78> Ok, it's getting clearer. So the glossary that Mel started here, is also marked where it's at in the actual chapter? <quaid> you may want to just read chapters, looking for where the writers already used some term (appears as italics in the rendered page) <quaid> and make sure those are in the Glossary of Terms <quaid> if you see a term that should be included, go ahead and include it <quaid> when we do the next conversion to XML, we'll make a new <glossary> from the Glossary of Terms <quaid> and in each chapter link back to the glossary with <glossterm> <quaid> in the current XML, it is *not* marked <quaid> but a plan for 0.9 is to actually mark it, yes <quaid> basically, open each XML file, find each term, and add the markup :) <quaid> we didn't have enough to do a glossary for 0.8, so we started the terminology collection <Emad78> That sounds good, I think I can make this happen. Some of it anyway. <quaid> great <Emad78> I'm just excited to help out. <Emad78> :) <quaid> I'll keep a watch on the page and help if I see anything worth noting. <quaid> +1^1 <Emad78> Might take me awhile to get going but, yeah keep an eye out. <quaid> this is the value of getting work out early, it makes other people notice it and realize they can help it get to the next level

Search