Conversation with #ubuntu-doc(14:49:37) The topic for #ubuntu-doc is: Ubuntu Documentation Team - visit https://wiki.ubuntu.com/DocumentationTeam to contribute | Get involved! http://www.mdke.org/?p=67 | Channel log at http://irclogs.ubuntu.com/ | Please observe the Ubuntu Code of Conduct - http://www.ubuntu.com/community/conduct
(14:51:46) philbull: hi guys
(14:51:57) philbull: anyone here for the Installation Guide meeting?
(14:52:15) DougieRichardson: philbull: yes
(14:52:50) philbull: hey dougie
(14:53:06) DougieRichardson: philbull: hi mate
(14:55:19) KelvinGardiner1: hi
(14:55:38) philbull: hi kelvin
(14:56:25) DougieRichardson: hi kelvin
(14:56:36) KelvinGardiner1: hello Dougie
(14:57:29) DougieRichardson: Rocket2DMn: I think phil's here for the meeting (not yesterday, lol)
(14:58:47) Rocket2DMn: o/
(15:01:08) jjesse left the room (quit: Read error: 110 (Connection timed out)).
(15:03:14) philbull: OK, we should probably begin
(15:04:02) philbull: The spec is here: https://wiki.ubuntu.com/Specs/KarmicInstallationGuide
(15:05:08) philbull: I was looking at some web stats for the wiki the other day, and it's clear that installation-related pages are really popular
(15:05:31) philbull: You can see for yourself: https://help.ubuntu.com/community/PageHits
(15:05:56) philbull: We currently have 2 official docs on installation:
(15:06:23) philbull: the Installation Guide https://help.ubuntu.com/9.04/installation-guide/index.html
(15:06:42) philbull: and the Switching from Windows guide https://help.ubuntu.com/9.04/switching/index.html
(15:07:18) philbull: The Installation Guide is just the Debian guide with some modifications
(15:07:34) philbull: as a result, it's technical and not really suitable for most new users
(15:07:58) philbull: The SFW guide is pretty out-of-date, so that's not much use either
(15:08:57) philbull: My plan is to produce a guide which is tightly-focussed on guiding non-technical users through installation
(15:09:23) philbull: What are people's thoughts on this idea?
(15:09:53) Rocket2DMn: You said that the SFW guide was out of date, why not update this instead of making a new document?
(15:10:20) mdke: it's a great idea, we've needed a good installation guide for ages
(15:10:44) mdke: there should be plenty of material on the wiki to work with
(15:10:54) philbull: Much of the SFW guide looks at migrating data and settings
(15:11:03) philbull: it was written before the Migration Assistant
(15:11:10) philbull: As such, most of it's obsolete
(15:11:22) philbull: It's also full of crap that users probably don't care about
(15:11:30) philbull: (it's my fault, I wrote most of it)
(15:11:50) KelvinGardiner1: I think its a good idea. The current guide have a lot of text and few screen shots to guide new users.
(15:11:51) Rocket2DMn: So are you intending to do away with that SFW?
(15:12:05) philbull: Rocket2DMn: yes, ideally.
(15:12:15) Rocket2DMn: Ok
(15:12:16) philbull: we can replace it with several more focussed documents
(15:12:36) philbull: at the moment, it tries to cover the needs of too many audiences at once
(15:13:25) philbull: KelvinGardiner1: Making the guide more friendly is a major objective for the guide
(15:14:19) KelvinGardiner1: ok
(15:14:32) philbull: I've done a bit of research into the most common installation-related problems over the last few weeks
(15:14:37) philbull: any guesses?
(15:14:47) DougieRichardson: If anything, SFW should probably just be a FAQ covering common pitfalls.
(15:14:54) DougieRichardson: Yes - formatting WIndows by mistake
(15:15:00) philbull: lol
(15:15:49) Rocket2DMn: video drivers, wireless cards, printers are common issues
(15:16:08) mdke: those are covered by the desktop documentation though
(15:16:17) philbull: Lots of people ask about installing from a flash drive
(15:16:39) philbull: partitioning, wubi, reinstalling Windows
(15:16:58) philbull: questions about resizing partitions, users worried about their data
(15:17:10) philbull: whether to go with 64-bit or 32
(15:17:22) philbull: system requirements!
(15:17:35) philbull: Most of these just aren't covered in the SFW guide
(15:18:48) philbull: My plan is to compile a list of the most common/important questions and cover those at appropriate stages throughout the guide
(15:19:41) philbull: The first section will be about getting Ubuntu (download ISO, ShipIt etc)
(15:20:08) philbull: Which installation methods to people think should be covered?
(15:20:16) philbull: s/to/do
(15:20:33) DougieRichardson: cd, alternate and usb
(15:20:41) philbull: what about wubi?
(15:20:46) KelvinGardiner1: yes wubi.
(15:21:00) Rocket2DMn: livecd, alternate cd, wubi, flash drive
(15:21:17) philbull: the problem is, I want to make the guide as short as possible
(15:21:18) DougieRichardson: img as well - unr uses it
(15:21:55) Rocket2DMn: well, there is already documentation on Wubi, right?
(15:22:37) mdke: I don't think alternate should be covered, that's what the installation-guide document is for
(15:23:21) Rocket2DMn: fair enough, i dont know if as many people have problems with the livecd as they used to
(15:23:37) philbull: I think that we should cover the livecd in depth and mention the others briefly, perhaps without screenshots
(15:23:54) philbull: at least, we should point to documentation covering the others
(15:24:05) KelvinGardiner1: Will the guide be stand alone in case the user has no internet connection, or will it point to other resources?
(15:24:13) mdke: I think it's important to distinguish installation method from installation media
(15:24:41) mdke: the installation process is actually the same whether you install from a cd, a usb stick or another typo of flash drive, I think
(15:25:17) mdke: that might affect the structure of the guide
(15:25:21) philbull: KelvinGardiner1: it should be standalone for the basic installation process, but anything else can be linked
(15:26:03) philbull: mdke: if the installer is the same for the different methods, then all we need to do is provide two different sections on "Getting Ubuntu"
(15:26:40) mdke: philbull: that's the sort of thing I had in mind yeah
(15:28:03) philbull: ok, that sounds good
(15:28:16) philbull: the next thing I had in mind was a troubleshooting section at the back
(15:28:27) philbull: it would cover common or scary problems
(15:28:49) philbull: e.g. "GRUB gives an error message!" or "I have a blank screen"
(15:30:06) philbull: any thoughts on this?
(15:30:17) philbull: again, it would have to be kept quite short
(15:30:44) mdke: sounds good to me
(15:31:30) KelvinGardiner1: This sounds sensible. Key thing is to get the machine to boot and get an internet connection. Then for other issues we can point to the wiki.
(15:32:31) philbull: I think it's important to decide on what should and shouldn't be covered
(15:32:48) philbull: I think we should decide on a preliminary list on the mailing list, perhaps
(15:33:14) mdke: possibly the way to look at that is to do a survey about common problems with installation in the community
(15:33:19) philbull: (BTW, the great thing about this guide is that it's going to be pretty modular, so lots of people can work on it at once)
(15:33:45) philbull: mdke: I've been analysing IRC logs to find out what people are asking about the most
(15:34:15) mdke: nice
(15:35:05) philbull: the most common "technical" problems seem to be GRUB errors and busybox/initramfs messages
(15:35:22) philbull: lots about the CD not booting, too
(15:35:39) mdke: yeah
(15:35:42) DougieRichardson: Looking on the forums since Jaunty's release, repairing grub and partitioning seem to be prevalent
(15:35:50) mdke: those are often caused by bad burns or downloads
(15:36:04) mdke: so I guess md5sum and the cd check will come into that
(15:36:45) philbull: My idea for the format of the troubleshooting sections is something like a short Microsoft KnowledgeBase article
(15:37:05) philbull: self-contained, text-only, references to related info
(15:37:14) DougieRichardson: Fantastic
(15:37:41) philbull: http://support.microsoft.com/kb/310064
(15:38:06) philbull: (maybe a bit friendlier than that, though)
(15:38:15) KelvinGardiner1: sounds good
(15:38:53) philbull: The only other thoughts on the structure of the guide I have is that there should be a decent index
(15:39:55) philbull: and that we should have a short "What Next?" section after the installation has completed
(15:40:07) philbull: (Kelvin, I think you suggested this)
(15:40:21) mdke: something that links on to our other documentation, maybe
(15:40:25) KelvinGardiner1: yes, I think this would be helpful.
(15:40:38) philbull: mdke: The "What Next" section would probably just point to the "New to Ubuntu?" section of the system docs
(15:40:53) ***mdke nods
(15:40:54) philbull: Someone will need to work on improving this too. It's not great at the moment
(15:41:13) mdke: maybe also introduce the answers to the the issues Rocket2DMn mentioned earlier, like hardware and internet
(15:41:18) mdke: by pointing to those docs
(15:41:52) philbull: perhaps those could be mentioned in a troubleshooting article, e.g. "My hardware doesn't work"
(15:42:11) philbull: Concerning the index, how translatable will that be?
(15:42:12) j1mc__ [email@example.com] entered the room.
(15:42:28) DougieRichardson: There are already troubleshooting parts of the Internet section, can't we xref to them?
(15:42:45) philbull: DougieRichardson: ideally, the guide will be self contained
(15:43:26) DougieRichardson: philbull: does that mean we can't have it pull information from other areas rather than have to have two similar documents to update?
(15:43:44) philbull: ah, no, that should be fine
(15:44:11) philbull: there shouldn't be much overlap anyway
(15:44:30) philbull: if we can point people at the system docs, then we should
(15:44:45) DougieRichardson: I'd have thought there would have been with Internet - especially wireless and modems.
(15:45:20) philbull: the troubleshooting should focus on problems where the user won;t have access to the system docs
(15:45:40) philbull: if the user can open Yelp, then we should just point at that
(15:46:04) DougieRichardson: ok.
(15:46:25) philbull: Next, the delivery format
(15:46:37) philbull: I was thinking: downloadable PDF, so the user can print it
(15:46:42) philbull: HTML on h.u.c
(15:47:08) philbull: maybe on the LiveCD as part of the system docs?
(15:47:37) DougieRichardson: The only problem with PDF is that they tend to get passed around rather than the link to their download which makes maintenance harder.
(15:48:11) DougieRichardson: That said, the individual solutions like MS KB articles would be suited to a PDF
(15:48:24) KelvinGardiner1: It would be nice to have a link on the desktop of the LiveCD to the guide. So its easy to find.
(15:48:40) philbull: I definitely want to get it linked to from the download page
(15:48:51) Rocket2DMn: DougieRichardson, your point about getting passed around is well taken, but isn't there advantage to that as well? LIke passing around install guides at a LoCo meeting?
(15:49:34) DougieRichardson: Rocket2DMn: Not if there are changes between releases, then we lose flexibilty in changing them.
(15:49:42) mdke: all those delivery methods are sensible, i think
(15:50:14) Rocket2DMn: yeah, but the document is going to be geared toward a specific release. And actually, not much changes with the install process
(15:50:21) mdke: philbull: on your translation question, I'm fairly sure that as long as the index is done using usual docbook tags, it will be translatable
(15:50:42) DougieRichardson: Rocket2DMn: If it's single sheets addressing issues then that's cool but an entire installation document, I'm not so sure
(15:51:12) mdke: I think since we provide the serverguide in PDF form, there's no reason not to provide this by way of pdf either, especially if it i a self-contained document
(15:51:49) philbull: mdke: I'll experiment with it
(15:52:01) philbull: nothing worse than an index which isn't in alphabetical order!
(15:52:47) philbull: OK, I'm pretty happy with most of this
(15:52:56) philbull: Any general comments? Anything we've missed?
(15:53:34) mdke: where will it be developed?
(15:53:58) philbull: I want to do all of the writing before we do any markup
(15:54:07) philbull: I guess that the wiki is the best place for that
(15:54:53) mdke: so are you going to work directly on the existing wiki Installation pages, or separately?
(15:55:11) philbull: no, we'll draft it on wiki.ubuntu.com
(15:55:48) mdke: how would you envisage the finished guide interacting with the existing Installation pages on the help wiki?
(15:56:05) DougieRichardson: Going back to the PDF thing and what Rocket2DMn said, it would be a good idea to have a single sheet covering installation with a FAQ covering common pitfalls on the back to hand out at LoCo meetings.
(15:57:03) j1mc_ left the room (quit: Read error: 110 (Connection timed out)).
(15:57:14) philbull: mdke: the existing stuff should redirect to the appropriate section of the official guide if that makes sense
(15:57:29) philbull: we can take lots of material from those pages anyway, I think
(15:57:34) mdke: good stuff
(15:57:36) philbull: Aha! License!
(15:57:58) philbull: CC-SA?
(15:58:14) philbull: DougieRichardson: that's a good idea
(15:58:31) DougieRichardson: Why CC-SA and not CC-NC-SA
(15:58:43) mdke: easy answer - nc is not a free licence
(15:58:49) philbull: The wiki is CC-SA
(15:58:50) mdke: and we use free licences
(15:59:16) mdke: but yeah, there's no real choice in the matter if material from the wiki is to be used
(15:59:19) DougieRichardson: So using CC-SA, this can be packaged as a book and sold?
(15:59:31) mdke: sure
(15:59:58) mdke: like any of our other material
(16:00:30) DougieRichardson: Why is NC not considered a free licence?
(16:00:50) mdke: because it prevents redistribution for a fee
(16:01:57) DougieRichardson: hmmm
(16:03:39) philbull: OK, last thing I want to cover is how to proceed with writing the guide
(16:03:47) philbull: who wants to work on what?
(16:04:33) DougieRichardson: I'm not sure of the structure, so I couldn't say.
(16:05:14) philbull: there's the introductory bit, the bit on "getting ubuntu", the actual installation process and then lots of troubleshooting bits (we need to decide on what to cover in this section first)
(16:05:27) philbull: plus, improving "New to Ubuntu?"
(16:06:05) DougieRichardson: Why not put up a list on a wiki page and people can assign themselves to sections to deconflict?
(16:06:16) philbull: that works for me
(16:06:24) KelvinGardiner1: ok
(16:06:45) philbull: there are also roles for people who want to research common problems, test the guide and produce screenshots
(16:07:04) DougieRichardson: I'll trawl the forum/net for common problems
(16:07:26) philbull: I'll put my list of problems from IRC on the ml
(16:08:07) DougieRichardson: Lets just consolidate the whole lot on wiki and reconveen next weekend with our thoughts?
(16:08:23) KelvinGardiner1: At the start of the trouble shooting section there should be a list of links to laptop specific wiki pages e.g. eeepc macbook.
(16:08:38) philbull: DougieRichardson: sounds good to me
(16:08:57) KelvinGardiner1: DougieRichardson: I'm happy with that.
(16:09:30) philbull: KelvinGardiner1: that's a good idea. If you have ideas for what might make a good troubleshooting topic, please add it to the spec:
(16:09:50) philbull: https://wiki.ubuntu.com/Specs/KarmicInstallationGuide
(16:10:00) DougieRichardson: I'm not trying to be negative BTW its just with OpenWeek, Uni assignments and writing the UNR branch I'm finding it difficult to stay on top so the wiki works for me
(16:10:53) philbull: DougieRichardson: that's fine, we have ages to work on this
(16:11:06) DougieRichardson: philbull: cool
(16:11:07) philbull: I won't have much time in the next couple of months myself
(16:11:58) DougieRichardson: I don't want to leave anything that's longer than six months either because I'm "on holiday" for four months later this year.
(16:12:24) philbull: It won't be that long, I want to get this ready for Karmic
(16:12:38) DougieRichardson: Oh OK
(16:13:17) philbull: OK guys, thanks for turning up
(16:13:28) philbull: I'll start a couple of topics on the mailing list later today
(16:13:41) mdke: thanks philbull
(16:14:05) DougieRichardson: Thanks phil, mdke are you hanging about? I wanted to have a quick chat about OpenWeek
(16:14:37) KelvinGardiner1: Will we meet next week?
(16:14:50) philbull: KelvinGardiner1: yes, we can do
(16:15:06) DougieRichardson: philbull: same time same bat-channel?
(16:15:47) philbull: maybe later in the day, I'm not home til Sunday evening next week
(16:16:07) DougieRichardson: ok, then after 1900 is best for me
(16:16:26) philbull: that should be OK by me
(16:16:35) KelvinGardiner1: works for me.
(16:16:53) DougieRichardson: Cool, lets put it on the wiki with everything else and I'll see you all then
(16:17:00) mdke: DougieRichardson: go ahead
(16:17:08) philbull: OK, thanks guys
(16:17:14) philbull: I'll be in touch later today
(16:17:18) philbull: (on the ml)
(16:17:33) philbull: KelvinGardiner1: are you subscribed to the ubuntu-doc mailing list?
(16:17:58) KelvinGardiner1: I've just done that.
(16:18:26) DougieRichardson: mdke: I just want to deconflict with what's needed to be said in the intro and the other sessions
(16:18:27) philbull: ok, cool
Attached FilesTo refer to attachments on a page, use attachment:filename, as shown below in the list of files. Do NOT use the URL of the [get] link, since this is subject to change and can break easily.
You are not allowed to attach a file to this page.