18:00:55 <randomuser> #startmeeting Fedora Docs Office Hours
18:00:55 <zodbot> Meeting started Thu Sep 11 18:00:55 2014 UTC.  The chair is randomuser. Information about MeetBot at http://wiki.debian.org/MeetBot.
18:00:55 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
18:01:14 <randomuser> #topic Writing Docs
18:02:12 <randomuser> #info Office Hours is an open discussion time with no formal agenda
18:04:05 <randomuser> RogerB_TX, over here :)
18:07:17 <randomuser> RogerB_TX, so, you were talking on ask.fp.o about writing some content about bootloader configuration?
18:09:24 <randomuser> okay, we can talk about the multiboot guide when he finds the channel :)
18:09:51 <randomuser> Capesteve, Sparks - are you in today? Should we further plans for a firewall guide?
18:12:00 <randomuser> #info review last office hours at http://meetbot.fedoraproject.org/fedora-docs/2014-08-28/
18:12:27 <randomuser> #info firewall guide content planning whiteboard at http://piratepad.net/9kMBB7VZlP
18:13:10 <randomuser> #info nb is going to set up our own piratepad instance
18:13:13 * randomuser ducks
18:13:15 <randomuser> #undo
18:13:16 <zodbot> Removing item from minutes: INFO by randomuser at 18:13:10 : nb is going to set up our own piratepad instance
18:15:52 <Capesteve> randomuser: I was out for dinner
18:16:39 <randomuser> Capesteve, I was *going* to go home for lunch. Some idiot left the key to my vehicle in the accessory position, and the battery is dead.
18:17:36 <Capesteve> randomuser: ahhh, how may peeps have access to your car keys?
18:17:52 <randomuser> Capesteve, I can't see how that's relevant
18:19:10 <Capesteve> well, it is  only you wots got access......
18:19:18 <randomuser> but.. one. One person has those keys.
18:19:24 <Capesteve> then we know who to tease
18:19:58 <Capesteve> randomuser: and I supposed its one of those American cars with marshmallow gearboxes that mean you can't push to start
18:20:42 <Capesteve> just two peddles , GO & SLOW
18:20:50 <randomuser> Capesteve, it's actually a Nissan SUV, but still, no manual trans
18:20:56 <Capesteve> ugh
18:21:30 <randomuser> In my defense, I sort of inherited it from my wife after buying her a new(er) car
18:22:33 <randomuser> I didn't need a vehicle for quite a while because I used the company fleet vehicle, and often enough that I didn't have time for much else
18:23:17 <randomuser> Sparks, there's an infra meeting right now, if you wanted to throw a cipher grenade in
18:27:57 <randomuser> So.. firewall-guide? Should we plan next steps, Capesteve ?
18:28:21 <RogerB_TX> Here I is!
18:28:32 <randomuser> hey, RogerB_TX
18:28:37 <RogerB_TX> lol
18:28:48 <Capesteve> randomuser: As Sparks indicated what parts he wants to keeps in his guide?
18:29:09 <randomuser> Capesteve, I don't think so
18:29:27 <randomuser> logically, we could limit the guide to common firewall admin tasks
18:29:44 <Capesteve> randomuser:{ I am trying to load that pad ......}
18:30:16 <randomuser> it did load here - i was quite surprised
18:30:17 <Capesteve> randomuser: Will you be the guide owner?
18:30:25 <randomuser> ahem
18:30:35 <randomuser> I would be willing to be the guide *coordinator*
18:31:04 <Capesteve> Same thing really...you can delegate chapters as you see fit
18:31:19 * randomuser nods
18:31:48 <randomuser> same to us - but 'owner' is powerful language with connotations of exclusion
18:31:59 <Capesteve> {its strange, the priate pad is hoted
18:32:07 <Capesteve> hosted near to me}
18:32:46 <Capesteve> randomuser: Strong Fences make good neibours ?
18:32:56 <randomuser> heh
18:33:06 <Capesteve> Have one owner as gatekeeper is best
18:33:46 <randomuser> yeah, it's just more inviting, semantically
18:33:53 <Capesteve> anyway, I could supply at least one chapter on Firewalld
18:34:09 <randomuser> Capesteve, we talked about linking from other guides; and I've been thinking about matching content with search queries
18:34:36 <Capesteve> The pirate pad loaded much faster after I allowed its scripts to run :)
18:34:45 <Capesteve> {silly me}
18:35:06 <randomuser> it could fit nicely to have linkable sections for "how to open port 80 for httpd with firewalld" (as an example)
18:35:10 <Capesteve> match Titles and index terms with those
18:35:33 <randomuser> but iterating through the list of named services makes me a little queasy
18:36:53 <randomuser> do you think a general "here is how you get a list of named services and enable them" is apropos enough for linking and discoverable enough for searching?
18:38:11 <Capesteve> possibly, but having one example of a typical first task for a new system would also help
18:38:22 * randomuser nods
18:39:12 <randomuser> RogerB_TX, you can jump in here to talk about what you'd like to work on at any time
18:39:22 <RogerB_TX> ok. tks
18:39:45 <Capesteve> simple example first, then show the user can get the info they need to do something else
18:40:05 <RogerB_TX> I am attempting to write a dual-boot guide -- more specifically how to recover a system when things go bad with Windows 8.1
18:40:13 <randomuser> Capesteve, sure, that makes sense.
18:40:55 <Capesteve> Can you explain about the headings from the Networking Guide, and they curly brackets, {}, in the pirate pad?
18:41:03 <randomuser> RogerB_TX, multiboot operation seems to be a big concern with our users; I'd really like to see a guide where common questions are answered
18:41:09 <Capesteve> s/they/the/
18:41:28 <RogerB_TX> The guide is tentatively called : Network Security Toolkit, Windows 8.1 Dual Boot Recovery Guide
18:41:41 <randomuser> Capesteve, I was encapsulating headings for the comment to apply to
18:41:56 <randomuser> RogerB_TX, let me show you what I started
18:42:05 <randomuser> https://git.fedorahosted.org/cgit/docs/multiboot-guide.git
18:42:08 <RogerB_TX> Its a rough area and I am going to need some technical assistance..
18:42:15 <RogerB_TX> I will look at that
18:42:25 <randomuser> fwiw, a dual boot guide and a security toolkit sound like a very different scope
18:42:45 <RogerB_TX> Where can I post what I have done so far and also those sections that are still pending?
18:42:55 <RogerB_TX> lol
18:43:19 <RogerB_TX> Yes, a good name is still needed
18:43:39 <randomuser> You can send anything to the docs list; however i think it would be most effective to work your content into the multiboot guide we have already started
18:44:20 <RogerB_TX> the name was referencing NST 20
18:44:23 <randomuser> the xml can be a little intimidating, but I/we can help with that
18:44:39 <RogerB_TX> sounds good. where do I go?
18:45:14 <randomuser> why don't we start by showing you how to get the source for the guide and build it, RogerB_TX ?
18:45:23 <RogerB_TX> sounds good.
18:45:46 <randomuser> okay, cool.  Open a terminal, and start with a `yum install git publican publican-fedora`
18:46:11 <RogerB_TX> I have no prior experience with this type of project. I apologize ahead of time for some of the hand-holding required to get me started
18:46:17 <RogerB_TX> ok
18:46:46 <randomuser> That's what this time is for :)  Later, you can read the Documentation Guide and explore related wiki pages
18:47:22 <RogerB_TX> ok. its running
18:48:26 <RogerB_TX> installing 65 packages now...
18:50:19 <randomuser> oh, and before I forget, RogerB_TX - Fedora Documentation is almost universally CC-BY-SA licensed.  You'll have to at least provide some assurance that you're ok with us distributing your work by signing up for an FAS account at https://admin.fedoraproject.org/accounts and "signing" the contributor agreement
18:51:12 <RogerB_TX> ok. np
18:52:12 <RogerB_TX> install complete
18:52:16 <randomuser> there are various 'groups' that your account belong to; some just indicate membership, some give privileges
18:52:47 <RogerB_TX> ok. Where do I go to get an account?
18:53:01 <randomuser> RogerB_TX, okay, cd your terminal to a good directory to store the docs in, and do `git clone https://git.fedorahosted.org/git/docs/multiboot-guide.git`
18:53:13 <RogerB_TX> nvm. got the account page up.
18:53:15 <RogerB_TX> ok
18:54:13 <RogerB_TX> ok. done
18:54:32 <RogerB_TX> with the git command...
18:54:39 <randomuser> now cd into the multiboot guide directory it made
18:54:56 <RogerB_TX> .
18:55:10 <RogerB_TX> ok done
18:55:10 <randomuser> inside you'll have a publican.cfg file that defines the project, and an en-US directory with the doc's XML
18:55:19 <RogerB_TX> yep. see it
18:55:41 <randomuser> you can get the gist of the document structure with `publican print_tree`
18:55:50 <RogerB_TX> ok
18:56:19 <randomuser> to build it, use the command `publican build --langs en-US --formats html-single`
18:56:52 <randomuser> there are other formats, but I find this one most convenient for review
18:57:11 <RogerB_TX> ok. just ran the print_tree to take a look... Running build now.
18:57:49 <RogerB_TX> done with build
18:57:52 <randomuser> it creates a 'tmp' directory for the output; you can open it with ie `firefox tmp/en-US/html-single/index.html`
18:58:00 <RogerB_TX> ok
18:58:39 <RogerB_TX> came right up
18:58:50 <randomuser> cool
18:59:39 <RogerB_TX> ok. so, i can look at it and see the structure. Where are the docs/sites I need to review to edit?
19:00:08 <randomuser> let's look at one of the files and talk about the structure
19:00:16 <RogerB_TX> ok
19:00:51 <RogerB_TX> Im really sorry. I gotta take this call. Can you give me 10 mins please?
19:00:54 * randomuser considers
19:00:55 <randomuser> sure
19:00:58 <RogerB_TX> tks
19:08:32 <RogerB_TX> Minor issue with a client's printer... Back.
19:09:07 <randomuser> wb
19:09:33 <randomuser> RogerB_TX, start with a glance at the root file, `cat en-US/Fedora_Multiboot_Guide.xml`
19:09:49 <RogerB_TX> .
19:10:27 <randomuser> You'll see that highest element in the XML structure is an 'article' - sometimes it's a book - and there are a bunch of includes
19:10:49 <RogerB_TX> yep
19:10:54 <randomuser> fairly straightforward so far?
19:11:01 <RogerB_TX> yep
19:11:34 <randomuser> ok, let's look at en-US/BOOT-BIOS_or_UEFI.xml - you can use whatever editor you prefer
19:11:44 <RogerB_TX> .
19:12:02 <randomuser> Under the <article> we have <sections>
19:12:24 <randomuser> the sections have an 'id' attribute that you can use for links
19:12:33 <randomuser> sections always have a title
19:12:37 <RogerB_TX> sorry. jas
19:12:53 <RogerB_TX> those files are going to be under Common-Content?
19:13:19 <randomuser> no, the common content comes from the brand, it's the same for every guide
19:13:46 <RogerB_TX> nvm. got it
19:14:01 <randomuser> ok
19:14:28 <randomuser> inside the sections we put whatever structural elements are appropriate; paragraphs, lists, notes, etc
19:14:39 <RogerB_TX> ok
19:15:23 <randomuser> The important thing to remember is that XML tags must always be closed, like this:  <para>words</para>
19:15:43 <RogerB_TX> ok
19:15:53 <randomuser> and there are rules about what elements can be parents of others, and what they can be children of
19:16:16 <RogerB_TX> Do we actually edit these files, or do we edit other ones and then after approval, bring it in?
19:16:33 <randomuser> Ok, let's talk about that process
19:16:49 <RogerB_TX> Sounds like I need to get up to speed on XML...
19:17:03 <randomuser> :) this is specifically docbook XML
19:17:16 <RogerB_TX> ok
19:17:35 <randomuser> docbook.org has a good overview, and out documentation guide has some on it - you'll get the feel for it as you go along, I think
19:18:01 <RogerB_TX> will be up there later tonight to get the scoop
19:18:09 <randomuser> RogerB_TX, don't worry too much about all the possible tags and the xml and such at first.  It's a lot easier to write first, and mark up later
19:18:22 <RogerB_TX> great. whew!
19:19:13 <randomuser> if you keep the structure very basic, I can help with the markup from there.
19:19:38 <randomuser> that said, let's go over how to share your work
19:19:47 <RogerB_TX> ok
19:20:20 <randomuser> if you have the appropriate privileges, you can commit your changes directly and push them.  terms that might not mean anything right now, but we'll get there :)
19:20:29 <RogerB_TX> :)
19:20:42 <randomuser> for now, pick a file to edit
19:21:14 <RogerB_TX> ok.UEFI.xml
19:21:53 <randomuser> Sure
19:22:14 <randomuser> Make a simple change; an introductory sentence maybe.
19:22:20 <RogerB_TX> ok. jas
19:22:59 <randomuser> you can also add <!--comments--> or <remarks>remarks have inheritance rules but don't appear in the build</remarks>
19:23:09 <randomuser> those are useful for outlining and such
19:23:14 <RogerB_TX> I wrote "First Time Edit":   <!-- General UEFI stuff; where grub lives, `uefibootmgr`, etc -->
19:23:15 <RogerB_TX> <xi:include href="UEFI-general.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
19:23:15 <RogerB_TX> First Time Edit
19:23:51 <randomuser> That won't work; you have content without a home in the XML structure
19:24:00 <randomuser> put it in a comment or remark block
19:24:15 <RogerB_TX> ok. so. I should mark that with <!--commment>, right
19:24:17 <RogerB_TX> ?
19:24:35 <randomuser> just inside these : <!-- words words words -->
19:24:58 <RogerB_TX> <!--First Time Edit-->
19:25:03 <randomuser> yup
19:25:12 <randomuser> now save the file and go back to the terminal
19:25:13 <RogerB_TX> ok
19:25:16 <RogerB_TX> ok
19:25:34 <RogerB_TX> done
19:26:04 <randomuser> one sec
19:26:32 <randomuser> now, we want to tell git to create a 'branch' for your work
19:26:38 <RogerB_TX> ok
19:26:58 <randomuser> the branch will give you a personal workspace, and a way to track your changes against the 'master' branch
19:27:08 <RogerB_TX> cool
19:27:16 <randomuser> like this: git branch callitwhatyouwantitisyourbranch
19:27:19 <RogerB_TX> this is alot like using source code from a git repository
19:27:34 <randomuser> heh, it *is* source code from a git repo
19:28:03 <randomuser> then check out your branch, `git checkout branchname`
19:28:11 <RogerB_TX> git branch RogerBTXContributions
19:28:56 <randomuser> great
19:29:01 <RogerB_TX> Switched to branch 'RogerBTXContributions'
19:29:49 <randomuser> now you want to commit your change. like this: `git commit en-US/UEFI.xml -m "some message that explains to your fellow contributors the change you are committing"
19:31:34 <RogerB_TX> [root@localhost en-US]# git commit en-US/UEFI.xml -m "First Time Edit performed under the tutilage of randomuser"
19:31:34 <RogerB_TX> error: pathspec 'en-US/UEFI.xml' did not match any file(s) known to git.
19:32:13 <RogerB_TX> wrong directory to issue the command?
19:32:21 <randomuser> wait a minute
19:32:25 <RogerB_TX> k
19:32:26 <randomuser> why are you doing this as root?
19:32:36 <RogerB_TX> dont know
19:32:42 <RogerB_TX> drop root
19:33:16 <randomuser> yes; move your files to your normal user directory, chown -R username /path/to/directory, then drop root
19:33:23 <RogerB_TX> the publication directory is off the root as /publish
19:33:29 <RogerB_TX> ok
19:33:30 <RogerB_TX> jas
19:33:58 <randomuser> as a rule of thumb, don't do anything as root unless you *know* there is a damn good reason to
19:34:55 <randomuser> and actually, let's hold off and not commit for a minute
19:35:02 <randomuser> there's one thing it would be good to do first
19:36:03 <randomuser> `git config --global user.name "Roger ROgerslastname"` and `git config --global user.email "your@email"`
19:36:07 <RogerB_TX> ok. jas
19:36:50 <randomuser> then go ahead with the commit.  You can execute git commands from anywhere inside the repo, but remember paths are relative
19:38:40 <RogerB_TX> ok. got everything moved over, chown'd and exited root. doing next task...
19:38:47 <randomuser> ack
19:42:42 <RogerB_TX> ok. ready to run the first commit
19:43:19 <randomuser> ok
19:44:21 <RogerB_TX> [pentest@localhost Publish]$ git commit en-US/UEFI.xml -m "First Time Edit performed under the tutilage of randomuser"
19:44:21 <RogerB_TX> fatal: Not a git repository (or any parent up to mount point /home)
19:44:21 <RogerB_TX> Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
19:44:47 <randomuser> sounds like you need to cd to the correct directory
19:44:54 <RogerB_TX> .....
19:46:13 <RogerB_TX> I have to get to the guide level, right?
19:46:37 <RogerB_TX> multiboot-guide
19:46:38 <randomuser> right; the root of the git repo will be the one with publican.cfg in it
19:46:42 <RogerB_TX> ok
19:46:44 <RogerB_TX> jas
19:47:16 <RogerB_TX> woohoo! [pentest@localhost multiboot-guide]$ git commit en-US/UEFI.xml -m "First Time Edit performed under the tutilage of randomuser"
19:47:17 <RogerB_TX> [RogerBTXContributions 41d3c67] First Time Edit performed under the tutilage of randomuser
19:47:17 <RogerB_TX> 1 file changed, 1 insertion(+), 1 deletion(-)
19:47:35 <randomuser> nice
19:47:39 <RogerB_TX> :)
19:47:54 <RogerB_TX> ok. so now I have my own branch to work with...
19:48:08 <randomuser> now, if you had commit privileges, you could do 'git push' and everyone would get those changes when the did a 'git pull'
19:48:24 <randomuser> until then, do this: `git format-patch master`
19:48:33 <RogerB_TX> Who watches over my branch and decides what will be incorporated and what will not?
19:48:35 <RogerB_TX> ok
19:49:32 <randomuser> it will create one file for each commit in your branch
19:50:20 <randomuser> you can email those files to me, or to the docs list, and we can apply them to the repo and bring your changes into the master branch
19:50:43 <randomuser> it will do content changes, commit messages and history, everything
19:50:54 <RogerB_TX> email the files that are created by the commit process, right?
19:50:59 <randomuser> right
19:51:30 <RogerB_TX> how often do I want to do a git format-patch master? Once before each writing session?
19:51:48 <randomuser> as often as you want to share your commits
19:52:08 <RogerB_TX> How will we avoid duplication of effort on a given area?
19:52:20 <randomuser> We'll have to talk about it
19:52:57 <RogerB_TX> I will be seeing everyone else's updated work each time I do a patch-master, right?
19:53:24 <randomuser> no, `git format-patch` only creates the patch files
19:53:25 <RogerB_TX> format-patch master...
19:53:32 <RogerB_TX> oh. ok
19:54:01 <randomuser> so here's what I'd suggest:  create a branch for a specific task, ie 'git branch uefibootmgr-instructions'
19:54:18 <randomuser> then make a series of edits and commits related to that task
19:54:24 <RogerB_TX> ok. so, that command is creating delta's against what i have changed and the master. Those files are the ones that you will look at...
19:54:30 <randomuser> yup
19:55:10 <randomuser> when they are applied, you can check out the master branch and do a `git pull`
19:55:52 <RogerB_TX> ok. right now I have a branch established for the multiboot-guide. I will be establishing a separate branch for each project I am assigned to work on -- even within the same guide?
19:56:15 <randomuser> then, go back to your private branch and `git merge master` will bring it back in sync.  Or, you can declare the work done and start a new branch after your branch is merged in
19:57:19 <randomuser> the main utility of having  a separate branch from master is to generate that delta file.  After that, it's whatever organizational structure seems appropriate
19:57:33 <randomuser> convention is to branch based on intent
19:58:09 <randomuser> honestly, we don't have a formal process for this part because not a lot of people have done it
19:58:35 <RogerB_TX> ok. so, for now, I stick with the multiboot-guide as my branch (since I have already established it as a fork) and from there contribute to a particular section, and then send along the delta files...
19:58:51 <randomuser> right
19:58:56 <RogerB_TX> got it
19:59:01 <RogerB_TX> whew!
19:59:15 <RogerB_TX> I now how hard it is to get those newbies inline! :)
19:59:19 <randomuser> hehe
19:59:23 <RogerB_TX> you have done a great job!
19:59:42 <RogerB_TX> I am saving this to a log for future reference...
19:59:53 <randomuser> Thanks!
20:00:21 <RogerB_TX> Is there a handy-dandy cheat sheet for these commands/processes somewhere?
20:00:25 <randomuser> You might also want to grab the guide from https://git.fedorahosted.org/cgit/docs/documentation-guide.git/
20:00:32 <RogerB_TX> nvm. I will just write it myself. :)
20:00:34 <randomuser> it's rough, but it has a lot of this info
20:00:44 <RogerB_TX> ok
20:01:07 <randomuser> and if you spot something missing, incorrect, etc feel free to make changes there, or at least complain :)
20:01:16 <RogerB_TX> hehehe ok
20:01:43 <randomuser> any questions about that process so far?
20:01:50 <RogerB_TX> ok. gonna run for now. Thank you again for your help. I will review the guides and get back with you soon.
20:01:58 <RogerB_TX> No questions for right now
20:02:02 <randomuser> ok
20:02:06 <RogerB_TX> take care!
20:02:24 <randomuser> I do think there are a few misconceptions in your ask post we should talk about later
20:02:31 <randomuser> but I too should move on with the day
20:02:53 <RogerB_TX> ok. sounds good - lets talk tomorrow???
20:03:04 <RogerB_TX> give me a time...
20:03:42 <RogerB_TX> BTW, all of my testing so far has been with NST 20. I should stick strictly to Fedora 20 for everything here, right?
20:03:45 <randomuser> well, I only block off daytime for this (UTC-0600) on thursdays, but I'm in and out all day
20:04:02 <RogerB_TX> ok.
20:04:04 <randomuser> yes, you should very strictly stick to Fedora
20:04:13 <RogerB_TX> got it.
20:04:27 <RogerB_TX> Well, some Thursday soon then...
20:04:34 <RogerB_TX> adios
20:04:40 <randomuser> evenings would be easier for me - and there's email too
20:05:16 <Sparks> randomuser: Bah...  I'll just wait for nb_.  It's not uber urgent.
20:05:26 <randomuser> RogerB_TX, later, thanks for stopping in!
20:05:37 <Sparks> randomuser: Plus, I think Fedora Infrastructure is already using the latest/greatest.
20:06:01 <randomuser> tsk tsk, Sparks - a missed opportunity to be disruptive
20:07:34 <randomuser> Sparks, that piratepad is still live, if you wanted to help make some headway on the firewall guide scope
20:13:08 <randomuser> It would be nice to have a defined scope, build an outline, and generally get it ready to farm out discrete tasks from
20:48:35 <Capesteve> Good night
21:57:26 <RogerB_TX> Does anyone know the command line to verify that hexchat is indeed using an encrypted connection?
21:58:14 <RogerB_TX> I put in the settings to use SSL for all servers, but I am not sure how to verify it...
22:06:29 <randomuser> you could use SASL for IRC; that either fails or does not
22:06:29 <RogerB_TX> nvm. All I need to do is fire up WireShark first, connect to HexChat, capture the connection and analyze.
22:06:42 <RogerB_TX> tks
01:04:02 <zoglesby> office hours are long nowadays
01:04:19 <nb> .listmeetings
01:04:19 <zodbot> nb: ('#fedora-docs', 'freenode'), ('#fedora-meeting', 'freenode')
01:04:21 <nb> wow
01:04:28 <nb> .addchair #fedora-docs freenode nb
01:04:28 <zodbot> nb: Chair added: nb on (#fedora-docs, freenode).
01:04:31 <nb> #endmeeting