User:Emad78/New Docs contributor FAQ dump

From FedoraProject

Jump to: navigation, search
Warning (medium size).png
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.

Contents

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.

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


<quaid> sorry that feels like such a shut-down <Emad78> Well that's why I wanted to talk to you. I would get a straight up answer. <quaid> I reckon, book leads tend to have an idea of what they think does and doesn't belong in a book ... but I hope folks are respectful with contributions. <quaid> not being familiar with the situation/details, though <Emad78> Right, and I just wanted to get some clarification that it isn't something I need to be all up in arms about. <quaid> for example, some of the writers on the Docs Team are working on system administrator documentation that will double in RHEL 6 <quaid> just so I understand more, what kind of guide and content? <quaid> Emad78: were folks disrespectful? Or ... something else? <Emad78> I think it was the security guide and I thought it might have some importing section for GPG. It has backups, exporting, most everything else. So I thought it could use some importing of keys section. <Emad78> quaid: No, not disrespecting or anything. But I was learning how to import gpg keys and there isn't anything in there. So I thought it could be added. <quaid> regarding the scattered comment, not sure ... could it be the lack and scatter of desktop-end-user type content? <quaid> regarding 'be bold', it sounds as if you are getting a mixed message, is that right?

  • fardad (~fardad@CPE0022759e2ef2-CM0014e88eeb56.cpe.net.cable.rogers.com) has joined #teachingopensource

<quaid> the thing with open collaborations is, it's OK to bring ideas forward and not have them fit in anywhere, in the end. <Emad78> Maybe I am getting a mixed message. That's why I wanted to talk to you.

  • fardad_ (~fardad@CPE0022759e2ef2-CM0014e88eeb56.cpe.net.cable.rogers.com) has joined #teachingopensource

<quaid> well, it definitely seems mixed at first

  • fardad_ has quit (Client Quit)

<quaid> for example, if you just went in and added that content, it might get taken right back out because other folks working the guide don't think it fits the vision. <quaid> ideally that's done in a discussion :) <quaid> so you are both encouraged to bring forward new ideas, and asked to understand that not all good ideas can fit anywhere (yet) <Emad78> Right, and I realize I don't want to just start adding content for that reason. <Emad78> Ok, well that sounds like something I need to realize. <Emad78> And I'm fine with that. <quaid> I wish I had time to really get a concerted effort at doing these types of smaller, easy to update end-user content via the wiki <quaid> get a wiki writing force working to cover all matter of useful bits, either locally or with a stub page that links out to an article on fedoraforum.org, fedoraanswers.org, etc. <Emad78> I just thought that when someone comments that documentation could be more, in one place, we could do that. But like you said maybe that's not part of the big picture. <quaid> Emad78: I'm still having a hard time feeling that it is fair for you to be told, "We can only have so much in the guides and in general you can only have your hand held so much" <quaid> at least, if someone can't articulate a vision that explains what does go where :) <quaid> Emad78: let's go back to that ITWorld article ... <quaid> did you feel some actions to derive from it? <Emad78> here is the comment in that article...... <Emad78> Which brings up a minor concern: there's some really good documentation out there for Fedora, and I was eventually always able to find what I needed -- but not always from Fedora or Red Hat sources. The Fedora documentation seems, on the whole, a bit more scattered than that found for openSUSE and Ubuntu. Third-party sites have picked up the slack, so like I said, you can get what you need eventually. To be fair, the docu <Emad78> mentation situation has vastly improved for Fedora from what it used to be, and the Fedora documentation site has a great interface. It just seems like there needs to be a little more content in there. <Emad78> quaid: That is from the article. <quaid> ok <quaid> https://fedoraproject.org/wiki/Category:Documentation <quaid> https://fedoraproject.org/wiki/Category:How_to <quaid> especially the first, scary <Emad78> Yeah, and maybe this guy just didn't look hard enough for the information. So I am just really *motivated* to try to add content. Might be a tad to BOLD. <quaid> ok, what about this ... <quaid> add a link to http://docs.fedoraproject.org/ in the F13 bubble that says, "Not finding what you are looking for, try the wiki" <quaid> and that links to ... maybe the Category:How_to page <quaid> the idea is, when you find something that needs writing, no matter how small (well, more than "how to use a mouse")

  • mchua is now known as mchua_afk

<quaid> if it's not in an existing document, write a wiki article <Emad78> Yeah, maybe that could take up some slack. I'm not saying anything is wrong with what we have now. I just thought the comment was motivating. <quaid> and make sure it gets, and if it's a how-to type article. <quaid> it's a good point ... <quaid> here's the quick bit of history: <quaid> when Red Hat Linux split to RHEL and Fedora Core <quaid> zero guides came over to the Fedora side <quaid> Red Hat kept a restrictive (non-free) license on the guides <quaid> so only a new installation guide was written <quaid> and it's really hard to write long guides from scratch in an open documentation community <quaid> not impossible, just hard <quaid> so docs were filled in all over <quaid> for a long time (and still somewhat) it was too hard to publish to docs.fedoraproject.org <quaid> (formerly fedora.redhat.com/docs) <Emad78> Well that clarifies it a lot more then. <quaid> anyway, eventually Red Hat released all that content <Emad78> So essentially, I could just go into the wiki and add the part about importing keys then. Right? <quaid> so there is overlap <quaid> and stuff that the community backfilled on e.g. fedoraforum.org <quaid> Emad78: yes, but make sure it's not there first :) <quaid> if it is, let's make sure it's in the how to category, updated for Fedora 12/13, etc. <Emad78> I'm pretty sure it's not there. Cause I was trying to find it and had to go *outside* Fedora to learn how to do it. <quaid> Emad78: my feeling is the best thing to do with your motivation is to use it on the wiki <Emad78> Ok, I can definitely do that. <quaid> Emad78: yeah, there is sometimes a feeling with writers that we would rather point to a canonical document at e.g. pgp.org rather than write yet-another-gpg-tutorial <Emad78> Right and that was exactly the feeling I was getting. e.g. going to outside sources. <Emad78> So are we trying to make the guides the end all, be all, of that particular piece of documentation. Or just keep the major stuff in there and, like you said, refer to the wiki for any special documentation.

  • sankarshan_away is now known as sankarshan

<quaid> Emad78: ideally, I think we'd want documentation to be like code -- we can all draw from a common upstream <quaid> but that is a harder problem than you and I are solving today :) <Emad78> Yeah, that is a little more involved.

  • rrix is now known as RRIX
  • RRIX is now known as rrix

<Emad78> So the situation is the guide owners are the last say in what goes into a guide? And good ideas, even though good, might not make it in at that particular time.

  • sumanah (~sumanah@cpe-24-193-113-134.nyc.res.rr.com) has joined #teachingopensource
  • sumanah (~sumanah@cpe-24-193-113-134.nyc.res.rr.com) has left #teachingopensource

<quaid> essentially, yes <quaid> same is if it were software, etc. <Emad78> Well I can agree with that. And I'm back on the level now. <Emad78> quaid: Well that pretty much clears me up for what I was wanting to get answered. Thanks for your time and talking with me. <Emad78> And maybe on an earlier time frame that at night we can get some more going. <quaid> ayup