/srv/irclogs.ubuntu.com/2013/09/01/#ubuntu-doc.txt

pleia2bkerensa: any luck finding that broken screenshot script and trying it out?18:13
pleia2I'm writing a getting involved blog post for the team and it would be great to give that broken script job to someone18:14
godbykpleia2: The script is called collect-screenshots.sh. It lives in the root dir of the repository.18:26
pleia2godbyk: ah, thanks!18:27
godbykpleia2: no problem. :)18:27
pleia2godbyk: oh, and you have email18:28
* pleia2 on docs this morning18:28
godbyknice18:28
pleia2we can chat about it here, nothing private about the mail18:28
godbyk'kay.18:28
godbykLet me skim through your doc. One moment18:28
pleia2The program 'bzr' is currently not installed.18:29
pleia2hehe, new laptops18:29
* pleia2 follows all her own instructions!18:29
godbykI take so many things for advantage like that. And when I set up a new PC I always discover just how many packages aren't installed by default. :)18:29
godbykThere are a couple ways we can handle volunteers:18:31
godbyk1. Just let them review anything they like and hope everyone doesn't choose to review the same few pages; or18:32
godbyk2. Assign volunteers to certain pages to help ensure full coverage of the current docs.18:32
pleia2my concern with 2 is that it seems like a big task18:32
pleia2we'll need to set up a mechanism to track this and for people to sign up quickly so they don't get bored and walk away18:33
godbykIt's usually not too bad. For the Ubuntu Manual, we just have a spreadsheet that tracks who is writing/editing each section or chapter.18:33
pleia2ah, spreadsheet is a good idea18:33
godbykPeople can request particular sections/chapters and we try to assign them based on preference.18:33
pleia2I used to like the wiki for these things, but so many people have trouble logging in to and editing the silly thing18:33
godbykAt the end, we often have some sections that are still missing authors/editors and we then request volunteers to fill those specific slots.18:34
pleia2cool18:34
godbykMaintaining tables on the wiki is especially bothersome, too.18:34
pleia2yeah18:34
pleia2so, shall I create said spreadsheet?18:34
godbykSure.18:35
godbykAlso, for volunteers who want to do some drive-by editing, they can just look at the current docs at help.ubuntu.com and let us know what needs to be updated.18:35
godbykThere may be some mismatches between the 13.04 docs and the work we've already done on 13.10, but I don't think the gap is very large at the moment.18:35
godbyk(This way the volunteers don't need to learn bzr or Mallard or anything. Just read the existing docs and tell us where the errors are.)18:36
* pleia2 nods18:36
pleia2is there an easy way to build the docs for viewing?18:37
pleia2for xubuntu 'make' in the doc directory makes an html version that's quite handy for normal people reviewing18:37
godbykThat's a list of all the .page files. We could group them a bit, too (e.g., a11y, accounts, add/remove, backup).18:38
godbykYou can run 'make' in the ubuntu-docs, too, but you'll need to have a few other packages installed first.18:38
pleia2wow, that's lots of pages :)18:39
godbykThankfully, most of them are quite short.18:39
pleia2I didn't actually realize the docs were so big18:39
godbykYou'll need the following Ubuntu packages: bzr xsltproc libxml2-utils yelp-tools yelp-xsl18:39
godbykI think running 'make html' will do the minimum amount of work to generate the html files.18:40
godbykReading the .page files (with Mallard markup) isn't too difficult either, but it's definitely easier to view the rendered HTML.18:40
pleia2ok18:40
pleia2oh gosh, it's taking like 4 days to do bzr branch lp:ubuntu/ubuntu-docs18:41
godbykbzr (or Launchpad) does seem awfully slow sometimes.18:41
pleia2godbyk: are you able to access this? http://etherpad.ubuntu.com/sUWEmOmlvR18:42
pleia2if not, I can add you to the etherpad team18:42
pleia2much easier than reviewing+updating static file in my /temp dir on my website18:42
godbykpleia2: Yes.18:43
pleia2ok cool18:43
godbykpleia2: One problem with viewing the html docs locally is that I think there are some http://help.ubuntu.com/... links in the docs so it may send you to the online docs at some point instead of the local files.18:47
pleia2godbyk: ah, interesting point18:47
pleia2some day when this bzr branch finishes I'll run through this process myself and see if there are any other gotchas18:48
godbykIt looksl ike most of the links to help.ubuntu.com are in the footer, so it may not be as big of a problem as I thought.18:50
godbykThere are some links to the community wiki, as well.18:51
* pleia2 nods18:51
godbykIn any case, I don't think it'll be a huge problem. If a bug gets reported multiple times, that's better than not getting reported at all.18:51
pleia2agreed18:51
pleia2ok, I'm going to share this spreadsheet with the list before sharing it in blog18:53
godbykSounds good.18:53
godbykSee what they think of the idea.18:53
pleia2done18:59
godbykI updated your spreadsheet usage to have the reviewers check the spreadsheet first to find a page that hasn't yet been reviewed.19:00
godbykHopefully that'll cut down on everyone reviewing the same few pages.19:00
pleia2\o/19:01
godbykShould I suggest that they call your home phone number if they have questions?  ;-)19:01
pleia2lol19:01
pleia2ok, this post looks good, thanks godbyk :)19:05
godbykNo problem. I'm happy to help. :)19:06
godbykHopefully this will help jump-start things a bit.19:06
godbykOne thing the spreadsheet won't help us with is determining what topics the documentation should cover that it currently doesn't.19:11
godbykAre there new features or default apps that we need to write new documentation for?19:11
pleia2that's a very good question, bkerensa tried to get some help from jono on that but came up empty19:11
pleia2the beta1 comes out this week and Ubuntu should have some release notes for it (they didn't do any alphas)19:12
pleia2I'm inclined to mostly crib from those unless we find a better way19:12
godbykOkay, we'll have to see what we can glean from those.19:12
godbykIt'd be nice if the developers/designers could shoot us an email or CC us on bugs when they add new features or change things.19:12
godbykAnymore, it seems like the documentation is an afterthought (if that).19:13
pleia2yeah, that would be nice19:13
pleia2the party line seems to be "read the blueprints" but there are like 100s :)19:13
godbykYeah, and many of the blueprints never come to fruition.19:13
pleia2yeah19:13
godbykThey stall out for one reason or another.19:13
pleia2I'm hoping that as the team becomes more visible again people will want to pay attention to docs and make sure their new stuff is advertised19:14
godbykI also get a little perturbed when it comes to breaking the UI freeze or documentation freeze.  Everyone seems fairly cavalier about that.19:14
pleia2yeah, I've really not been impressed with that lately19:14
pleia2Branched 112 revisions.19:15
pleia2w00t done19:15
godbykOn the few occasions I've been involved with those discussions, we've either allowed the freeze exception or, if we protested the exception, sabdfl overrode us anyway.19:15
pleia2godbyk: have you ever run this collect-screenshots.sh ? I'm wondering, do I just fire up a new 13.10 VM and try to run it and see what happens?19:15
godbykFinally! :-)19:15
godbykYeah, you can run it in a VM to see what happens.19:16
godbykI wouldn't run it on your main installation because it changes the screen resolution and other things without prompting.19:16
godbykBe prepared for windows to start opening and closing a bunch, too.19:16
pleia2ok, I'll do that in a bit and send my report to the list, then share it on my twitters and things so we can find someone to fix it19:16
pleia2hah, I run Xubuntu anyway :)19:16
godbykThe script tries to set the screen resolution then automatically run programs and take screenshots.19:16
* pleia2 nods19:16
godbykThanks. It's been on my to do list for a while and I just haven't gotten to it yet.19:17
pleia2my husband's best friend is in town so I have a lonely day while they go tear up the town together ;)19:17
godbykAh, nice.19:17
pleia2although, I haven't eaten in a while and I should probably go do that19:18
pleia2I'll post blog thing and play with script upon my return19:18
godbykSounds good.19:18
godbykI'm going to take a shower and then find something to eat, too.19:18
* godbyk slept in this morning.19:18
* pleia2 too19:18
pleia2see you in a bit then19:18
godbykSee you.19:18
godbykpleia2: Well, I'm finding a few bugs in the collect-screenshots.sh script...21:37
godbykLine 110: dir should be $dir21:38
godbykLine 114: -eq should be ==21:39
pleia2I learned that you need to install xdotool before it'll work21:41
godbykOh, yeah.21:41
godbykand imagemagick21:41
godbykSee the comment at the top of the script.21:41
godbykWe should add checks for those programs so it installs them if they're missing.21:42
pleia2I am supposed to read the script before I run it?! details details :)21:42
godbykYeah, no kidding!21:42
godbykI figured it out by running the script and reading the errors. :-/21:42
pleia2hehe21:42
pleia2gosh, running ubuntu in a vm these days isn't exactly zippy21:46
godbykYeah.21:47
godbykIf you don't have a 3D graphics card it runs dog slow.21:47
godbykYou know what would be nice?  If someone had added comments to this script. :-)21:48
pleia2hehe21:50
* pleia2 follows the instructions this time and runs it21:50
pleia2ta-da! http://princessleia.com/journal/?p=844321:52
godbyk\o/21:53
godbykWell, I finished running the collect-screenshots.sh script.21:55
godbykAnd I have a handful of screenshots in the ~/.ubuntu-help/en_US/figures/ dir.21:55
godbykSome of them seem okay, but I think some might be incorrect.21:55
godbykI think there are race conditions in the script.21:55
* pleia2 nods21:55
godbykI think it means to kill all the apps it opened before making the next screenshot.21:56
godbykBut since everything is running asynchronously it doesn't always work out.21:56
godbyk(Or something)21:56
godbykhttp://kevin.godby.org/private/ubuntu-doc/figures/  ← here's what I ended up with21:58
godbykI think http://kevin.godby.org/private/ubuntu-doc/figures/unity-appmenu-intro.png, for example, is too cluttered.21:58
pleia2interesting, different than mine21:59
godbykDoes yours close the apps more quickly?21:59
pleia2actually, looks very similar except for unity and unity2 (I didn't get those)21:59
godbykAh.. the unity.png file won't exist until you fix a bug in the script.22:00
godbykTwo bugs.22:00
pleia2and nautilus worked ok for me, but my unity-appmenu-intro.png was wrong too, I got the calendar :)22:00
godbykLine 110: add $ before dir22:00
godbykLine 114: change -eq to ==22:00
pleia2heh, for -exit I got the calendar too22:01
godbykHmm.. are you running at 1024×768?22:01
pleia2yeah22:02
godbykOnce you run the script you have to keeps your hands off the mouse, too. It'll move the mouse pointer around programmatically to click on those menus.22:02
pleia2http://princessleia.com/temp/figures/22:03
godbykHa! Between the two of us we might have just over half the screenshots. ;-)22:04
godbykWhat a brittle way to take screenshots... relying on magic coordinates to never change, particular screen resolutions, random files downloaded from urls that could vanish at any moment, ...22:05
pleia2yeah22:09
godbykI just pushed the couple bug fixes I mentioned above (lines 110 1nd 114).22:29
pleia2great22:35
godbykI'm working on spiffying up the script, too.22:55
godbykAdding more status info (with colors!) and adding comments so it's easier to see what's happening (or should be happening).22:56
pleia2\o/23:02
godbykWow, someone was feeling clever!23:07
godbykIn the script, they set the time to be the same as the Ubuntu version.23:07
godbykFor us to do that with 13.10, however, we'll have to switch to military time.23:08

Generated by irclog2html.py 2.7 by Marius Gedminas - find it at mg.pov.lt!