|
|
| (93 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| == Docs FAQ ==
| | {{Draft}} |
| | |
| ===What do I need to have installed to be able to work with the Documentation Project?===
| |
| | |
| ===Do I need to have any specific text editor to be able to edit documents?===
| |
| | |
| ===What is this "git" I keep hearing about? How does it pertain to the Docs Project?===
| |
| | |
| ===What do I need to configure git to work with documents?===
| |
| | |
| ===What basic commands to I need to know to use git?===
| |
| | |
| ===How do I build a document using publican?===
| |
| | |
| ===What is publican?===
| |
| | |
| ===Who is the Docs Project Leader?===
| |
| | |
| ===Where is the best place to get immediate help?===
| |
| | |
| ===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.
| |
|
| |
| ===Where can I learn about the open source world?===
| |
| | |
| teachingopensource.org
| |
| https://www.theopensourceway.org/wiki/Stuff_everyone_knows_and_forgets_anyway#Turn_annoying_newbies_in_to_instant_contributors_with_the_power_of_To_Document
| |
| | |
| | |
| | |
| | |
| * <quaid> one nice thing about IRC is the asynchronous nature of it, I leave my client running all the time in a way I can detach from, so if you ask questions or comment, I see it later and reply, we have discussions that span timezones and never even be together in the channel at the same time.
| |
| | |
| <quaid> for example, in the mailing list many more get to read the above advice; but it can be inconvenient for every little thing
| |
| <quaid> anyway, don't be afraid to leave questions in the channel and see who answers :)
| |
| <quaid> because we are "just like" coding projects, even non-docs team participants might know the right answer, etc.
| |
| <Emad78> Yeah, and I figured these were pretty easy to answer. And since I was on here I thought I would see if anyone was around.
| |
| | |
| <quaid> since the textbook I'm working on includes this sort of material, I'll likely reference it to the list later, see if it's useful to newer contributors, etc.
| |
| <Emad78> You think we could do a new contributor FAQ type thing??
| |
| | |
| | |
| | |
| | |
| <quaid> Emad78: 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!
| |
| | |
| | |
| | |
| > You emailed before I could get the chance to email you. Quick again. I
| |
| > was going to ask you about the EDITOR and VISUAL. And I remember what
| |
| > you said about putting it into bash.rc. And I will just put them in
| |
| > there since I'm the only user. But do I need to put anything in there to
| |
| > allow them to do their job. I don't really know the lingo but, like a
| |
| > header or title. Something like that, to allow them to work. Or just put
| |
| > them in straight away? I'll do that then we can figure it out if it
| |
| > doesn't work.
| |
| | |
| If you are going to do it system-wide, it is probably better to put it
| |
| in /etc/profile.d. This has a file per "thing" you want to do. I have
| |
| an "editor.sh" that sets this up. It has the lines I said, except emacs
| |
| of course, instead of gedit, and it begins with a ~!/bin/sh. Not so
| |
| sure it is really necessary, but I also gave it chmod +x. During logon
| |
| not all scripts seem to need execute, but I do it by habit. So my
| |
| entire /etc/profile.d/editor.sh is:
| |
| | |
| | |
| EDITOR=emacs
| |
| VISUAL=emacs
| |
| export EDITOR VISUAL
| |
| | |
| | |
| | |
| | |
| > So now. How does the pecking order work. Like I just jumped in and did
| |
| > that one bug for the user-guide. Now I applied to be on the group and
| |
| > got approved. So does that mean I can just jump in and do any bug I feel
| |
| > comfortable with doing? Do I need to ask permission from the owner? How
| |
| > does all that work out?
| |
| | |
| Of course, it is good form to talk to the owner, but the rule in Fedora
| |
| is kind of "don't ask, always tell!". The philosophy is as little
| |
| governance as possible. Max Spevack did an excellent talk, I'll see if
| |
| I can't find the link. We try to be ruthelessly open. Whenever
| |
| possible all decisions are made on the mailing list, although a lot of
| |
| on the fly things happen on IRC. IRC is kind of open, but people who
| |
| don't happen to be there don't see it. We try to document anything
| |
| significant on the wiki.
| |
| | |
| Sparks is the Docs Project Leader, he has been under the weather lately
| |
| so he wasn't around much over the weekend. Sparks works as a contractor
| |
| for the military in Virginia. I think he is kind of a young guy, maybe
| |
| 30-ish. (I'm an old guy in case you didn't realize!). The Wikiczar is
| |
| ianweller, he is the expert on all things wiki, and is in the process of
| |
| looking for a college, so we have all ends of the spectrum.
| |
| | |
| stickster is the Fedora Project Leader, he may be the only person paid
| |
| to do this Fedora stuff full-time, but there are LOTS of paid Red Hat
| |
| folks working on Fedora. Stickster is the guy the magazines interview
| |
| about Fedora. quaid is Red Hat's "Community Architect". I think quaid
| |
| and stickster started the Docs Project, but for a while stickster was
| |
| pretty much a one-man show, so he really knows the space. He has been
| |
| less involved since I've taken over release notes and spevack stepped
| |
| down as Fedora Project Leader. Spevack is now heading the Ambassadors.
| |
| Probably the only part of Fedora that actually has a budget!
| |
| | |
| > What do I do if I'm just reading a random document, like say the livecd
| |
| > document. And I come across some errors in grammar or what not. Do I
| |
| > fill out a bug and can just jump right in fix it. And then close the
| |
| > bug?
| |
| | |
| That would work. If there is an owner, nice to tell him. The owners
| |
| are listed on the meeting page for most of the docs.
| |
| | |
| > Sorry for all the questions. If there is a doc to read on all that I can
| |
| > do that. But I was just wondering how the whole system worked and I
| |
| > didn't want to step on toes, you know?
| |
| > I mean I wouldn't do anything without asking first anyway but just
| |
| > curious.
| |
| | |
| You know, if you really screw things up badly, with git it isn't a big
| |
| deal do undo stuff. After translations start in earnest it can get to
| |
| be messy, but you can always go back. One of the nice things about git.
| |
| | |
| OK, on your other email, most of the really important stuff is in
| |
| ~/.ssh, so if you back up ALL your user files, you should be good.
| |
| | |
| --McD
| |
| | |
| == Read First ==
| |
| | |
| * https://www.theopensourceway.org/wiki/Stuff_everyone_knows_and_forgets_anyway#Turn_annoying_newbies_in_to_instant_contributors_with_the_power_of_To_Document
| |
| | |
| * http://teachingopensource.com/index.php/Textbook_Release_0.8
| |
| | |
| * http://www.youtube.com/watch?v=LJXyeIS-eIU
| |
