Log for #documentation: 2004-04-08 (edited)
-------------------------------------------
20:49 < dwx> so, fantasai, question?
20:49 < fantasai> wow, fast response :)
20:50 < fantasai> (hang on, my sister is a bit upset right now...)
20:57 < fantasai> ok
20:57 < fantasai> sorry about that ^^;;
20:58 < fantasai> actually, let me just forward you my email
20:58 < fantasai> first
20:59 < fantasai> sent
21:00 < fantasai> basically, I want to start organizing the end user docs by creating a proper index of them
21:00 < fantasai> not just listing help sites
21:00 < fantasai> but creating a master index of all the documents on those sites (including mozilla.org, of course)
21:00 < fantasai> organized by topic
21:01 < fantasai> 'coz right now, I can go to /docs/end-user
21:01 < fantasai> and see a list of sites
21:01 < fantasai> but it won't help me find out how to configure my mail prefs or whatever
21:01 < fantasai> because I don't know which site has that particular tutorial
21:01 < dwx> www.mozilla.org/community/
21:02 < dwx> one hundred+ of site to sort through :-(
21:03 < fantasai> yes, I see that... how is this a problem?
21:04 < fantasai> I mean, it's definitely a problem for the user; that's what we're trying to solve
21:04 < fantasai> as for going through all of those, I don't think we need to do *everything*
21:04 < dwx> I'm saying it takes a lot of effort just to get there
21:04 < fantasai> we just need to index a few big sites
21:05 < fantasai> to get up the framework
21:05 < fantasai> once that's done, we can advertise the new index on mozillazine and ask authors to submit their work to us
21:06 < fantasai> eventually, I'd like to get most of them *hosted* on mozilla.org, but I don't want to attempt that for awhile yet :)
21:06 < dwx> are you talking about some kind of database?
21:07 < fantasai> for hosting? no
21:07 < dwx> the "framework" part
21:07 < fantasai> well, we might create an auto-index database to help searching
21:07 < fantasai> but everything should just be files in the CVS tree
21:08 < fantasai> by the framework part, I mean categorizing a significant number of files
21:08 < fantasai> so that the organizational structure becomes self-evident
21:08 < fantasai> and other people can easily figure out where new documents will go
21:09 < fantasai> I'll oversee it; I'll want to, because once we're ready to start hosting docs, the URI hierarchy will be based on how we've organized the docs in the listing
21:09 < fantasai> and I'm very picky about URIs :)
21:10 < dwx> okay
21:10 < dwx> but I'm still not sure where I could help
21:10 < fantasai> I'm asking you about it (and you can email me comments later, too, of course) because I know you're a lot more familiar with end-user docs than I am
21:10 < fantasai> One thing I'm not sure of is where to put them
21:10 < fantasai> another is how to handle versioning
21:11 < fantasai> and that's a question I know you've thought about
21:11 < fantasai> you were commenting on versioning in some bug somewhere on the start pages and the Getting Started Guide
21:12 < dwx> my view is that everything should be of print quality, e.g. they should not be changed
21:13 < fantasai> my view is that one should be able to update things to correct them and/or explain more
21:13 < fantasai> that's the advantage of having docs online
21:13 < dwx> so we need to QA our doc
21:13 < fantasai> still won't catch everything
21:13 < dwx> if we update a doc for a newer version, someone needs to check that everything in the doc applies
21:13 < fantasai> the question isn't whether the *document* is static or not
21:14 < fantasai> it's how it applies to the program versions
21:14 < fantasai> updating a Mozilla 1.4 doc to better reflect 1.4 is a good thing
21:14 < fantasai> you agree, don't you?
21:14 < dwx> sure
21:15 < fantasai> the problem we have is that the same document, for Mozilla 1.4
21:15 < fantasai> can apply equally well to 1.5 and 1.6
21:15 < fantasai> but, say, not to 1.7
21:15 < fantasai> because there were changes to that aspect of MOzilla during the 1.7 cycle
21:15 < fantasai> now
21:16 < fantasai> we have 4 Mozilla -- document mappings
21:16 < fantasai> three of them result in the exact same document
21:16 < fantasai> one doesn't
21:16 < dwx> huh?
21:17 < fantasai> 1.4, 1.5, and 1.6 Mozilla all have the same document because nothing's changed between these versions
21:17 < fantasai> 1.7 has a different document
21:17 < fantasai> it's all on the same topic
21:17 < fantasai> ok?
21:17 < fantasai> here, let me give a concrete example
21:18 < fantasai> Suppose there's a document on table backgrounds in Mozilla
21:18 < fantasai> table backgrounds behave the same in 1.4, 1.5, and 1.6
21:18 < fantasai> so if I look up the documentation for any of those
21:18 < fantasai> I'll get the same exact info
21:19 < fantasai> the behavior changed, however, during the 1.7 cycle
21:19 < fantasai> so if I look up the documentation for 1.7, I'll get different info
21:20 < fantasai> I think you'll agree that we want to have the documentation for 1.5 available even after 1.7 has been released right?
21:20 < dwx> yes. no doc should be removed
21:21 < fantasai> the question is, does the pre-1.7 documentation all live in the same place
21:21 < fantasai> or does each version have it's own copy?
21:21 < dwx> no, we shouldn't have one doc for each version
21:21 < fantasai> ok. why?
21:23 < dwx> if we have doc on XXX for version 1.4, the doc should clearly say the doc is for 1.4. If nothing on the subject change in 1.5 and 1.6, then we don't change it
21:23 < dwx> if there is change for 1.7, we can create a new doc
21:23 < fantasai> if the doc is clearly labeled for 1.4
21:23 < fantasai> then where do the 1.5 people go, and how do they know the doc is still relevant?
21:24 < dwx> Say the user search for articles on the subject, the results would return two docs, one for 1.4 and one for 1.7
21:24 < dwx> The user should be able to determine that the one for 1.4 is useful for 1.5 and 1.6
21:24 < fantasai> We'd have to label the 1.4 doc as 1.4 - 1.6
21:25 < fantasai> because otherwise the users will be confused
21:25 < dwx> Because we have limited resource, we don't want to verify every doc after every release. We need to cut down the work required
21:26 < dwx> This also avoid the situation where we update one thing in a doc but forgot to check for another
21:26 < fantasai> that problem would apply to the 1.4 -> 1.7 case
21:27 < fantasai> not 1.4-1.6, since nothing's changed
21:27 < fantasai> if there's a substantial change, then we need a new doc
21:27 < fantasai> but it probably won't be complete rewrite; just an update
21:27 < dwx> fantasai, how do you know if nothing changed?
21:28 < fantasai> *nods* I don't.
21:28 < fantasai> but if I don't know that there's a change, I won't update it
21:28 < dwx> exactly
21:28 < fantasai> so I won't get the "update one thing but not another" problem in that case
21:29 < fantasai> just a "missing update" problem
21:29 < dwx> the thing is, right now, when somebody files a bug pointing out something needs to be updated, somebody would change that "without reviewing the whole doc"
21:30 < fantasai> that's a problem, then..
21:30 < fantasai> I can understand "without rewriting the whole doc"
21:30 < fantasai> that's reasonable and necessary
21:30 < fantasai> but "not reviewing the whole doc" is a problem
21:30 < fantasai> if the docs are small, it becomes less of a problem
21:31 < dwx> also, if there is trivial change, we shouldn't update it either, because we don't want to review "whole documents" all the time
21:31 < fantasai> if there is a trivial change to reflect the new version or to correct a mistake?
21:31 < dwx> both
21:32 < fantasai> if it's to correct a mistake, the version shouldn't be changed
21:32 < dwx> for example, if there is a new feature, like a menu item, and how to use it is self-evident, we don't need to add info on that
21:32 < fantasai> so the missing review isn't a problem
21:33 < dwx> for "correcting factual mistake", sure
21:33 < dwx> not for minor grammar mistake though. Such should not happen in the first place
21:35 < fantasai> it'll happen anyway :)
21:36 < dwx> yes, and something we can live with
21:36 < dwx> and because we can live with that, we should just ignore trivial mistakes and focus more on important things
21:37 < fantasai> if someone wants to make a grammatical fix, I don't see why that's a problem
21:37 < fantasai> it's not something we need to discuss
21:37 < fantasai> though
21:37 < fantasai> because it should not change the status of the document at all
21:38 < fantasai> let's take the getting-started guide as an example
21:39 < fantasai> suppose, just for arguments sake, that it's at /support/mozilla/something
21:39 < fantasai> where something needs to reflect both the topic and the version number
21:40 < fantasai> if I have /support/mozilla/1.6/getting-started
21:40 < fantasai> then we get the problem where you need a doc for every version
21:40 < fantasai> if I have /support/mozilla/getting-started/1.6
21:40 < fantasai> the user has to filter through version numbers every time they look up a doc...
21:40 < fantasai> :(
21:42 < fantasai> we could put an index of all 1.6 docs at /support/mozilla/1.6
21:42 < fantasai> and an index of all 1.7 docs at /support/mozilla/1.7
21:42 < fantasai> if the getting-started guide hasn't changed
21:42 < fantasai> then the 1.7 index would link to /support/mozilla/1.6 ...
21:43 < fantasai> what happens if the getting-started guide for 1.7 needs to link to a command-line-args doc that's new for 1.7?
21:44 < dwx> depends on what the "need" is
21:44 < fantasai> command line args have changed
21:44 < fantasai> a new one's been added
21:45 < dwx> then add the link to the command line arg doc, not the get-started doc
21:46 < fantasai> it's not a link, it's a table row of text that gets added
21:46 < fantasai> at any rate, the command line arg doc for 1.7 does not appy to the get-started doc
21:46 < fantasai> for 1.6
21:46 < fantasai> err..
21:46 < fantasai> the command line arg doc for 1.7 does not apply to Mozilla 1.6
21:47 < fantasai> if I'm using Mozilla 1.7 and I'm reading the get-started doc and I want to learn about command lines
21:47 < fantasai> I should get the 1.7 command line doc, not the 1.6 command line doc
21:47 < fantasai> but if I'm using 1.6, and I'm reading the get-started doc
21:47 < fantasai> I should get the 1.6 command line doc
21:47 < fantasai> not the 1.7 one
21:48 < fantasai> because the 1.7 one has an option that's not in my version
21:48 < dwx> no. If you are reading a 1.6 doc, then the link you follow should go to a 1.6 doc
21:48 < fantasai> what does the 1.7 user do then?
21:48 < dwx> if there is an updated doc, then the target doc should have a link to it
21:49 < fantasai> that's not very obvious
21:49 < fantasai> the user has to check the top of every doc to make sure it's the correct version?
21:49 < fantasai> that's not going to happen
21:50 < fantasai> they'll get the wrong doc at some point in the chain of links
21:50 < fantasai> and it could be a very wrong doc
21:50 < fantasai> it could be a very wrong doc for lack of updating
21:50 < fantasai> but if the updated one is there...
21:51 < dwx> fantasai, but what if we update get-started doc?
21:51 < dwx> It would mean if we update "one" doc, we'll need to update a bunch of other docs
21:51 < fantasai> what if..
21:52 < fantasai> what if we used the /support/mozilla/1.0/get-started URI
21:52 < fantasai> 1.6, rather
21:52 < fantasai> and then had the command line options at
21:52 < fantasai> /support/mozilla/1.6/command-line-args
21:52 < fantasai> for 1.7, the updated doc is
21:52 < fantasai> /support/mozilla/1.7/command-line-args
21:53 < fantasai> um
21:53 < fantasai> suppose it links back to get-started
21:53 < fantasai> if we're using relative links
21:53 < fantasai> it'll go to /support/mozilla/1.7/get-started
21:53 < fantasai> I think we can do something server-side
21:53 < fantasai> to get the server to serve up /support/mozilla/1.6/get-started
21:54 < fantasai> as /support/mozilla/1.7/get-started
21:54 < fantasai> so all the links from that doc will go to 1.7 docs
21:54 < fantasai> but the content of the page will be 1.6 content
21:54 < fantasai> will the 1.6 version number
21:54 < fantasai> in the header
21:54 < dwx> that will screw up Google
21:54 < dwx> if the doc isn't updated, we shouldn't pretend it is
21:55 < fantasai> we're not
21:55 < fantasai> it still says 1.6 on it
21:55 < fantasai> but the links will all go to the right version of docs
21:56 < dwx> no. it's too complicated. How are you going to sell this to doc writers? And what guarentees you that linking doesn't go wrong?
21:57 < fantasai> that the rewrite mechanism will always drop down a level until it finds a doc to send back
21:57 < fantasai> if it's an old doc, it will of course eventually find the target doc at its own level
22:01 < fantasai> dwx, the alternative is to offer the user a complete set of outdated docs even when new ones exists
22:01 < dwx> there should be better way of getting users find the right doc
22:01 < fantasai> do you want that?
22:02 < fantasai> like what?
22:02 < fantasai> we could use a database and numbered records
22:02 < fantasai> but that would give you the same result
22:02 < fantasai> with the only change being that the URI doesn't have the version number in it
22:06 < dwx> not sure. but as long as we don't change docs unneccessarily, it's fine
22:06 < dwx> let's talk about http://bugzilla.mozilla.org/show_bug.cgi?id=236483
22:07 < dwx> let's say a 1.4 doc says Mozilla 2.0 will become a collection of standalones, and at 1.5 that changes. Should we update the 1.4 doc?
22:08 < dwx> in another words, should we only update things related to using the products, or should we consider things that change with history?
22:09 < fantasai> depends on what the 1.4 doc is used for
22:10 < fantasai> things like the roadmap should obviously not be changed
22:10 < fantasai> the reason is that that document is *dated*
22:10 < fantasai> a document announcing 1.4 shouldn't be updated
22:10 < fantasai> because it's *dated*
22:10 < fantasai> a document on how to use 1.4 /should/ be updated
22:10 < fantasai> because it is not dated
22:11 < fantasai> it applies equally whether it's 2003 or 2030
22:11 < fantasai> let me put it this way
22:11 < fantasai> if the doc says go to netscape.public.somethingsomething for user help
22:11 < fantasai> and netscape kills that newsgroup
22:11 < fantasai> should we updated it to say go to mozilla.users.something?
22:12 < fantasai> (btw, I'm sorry about my grammar slips; my typing is a bit hazardous today)
22:13 < fantasai> if a book comes out in print, and we have an online version, a copy that matches the book exactly should be offered somewhere
22:13 < fantasai> but a version that incorporates errata should be available as the principal version
22:14 < fantasai> but that only applies because we need to match a print version which _can't be changed_
22:14 < fantasai> (then we can offer a diff as the errata doc :P)
22:15 < dwx> and if a doc is "intended for print"? e.g. it is printed sometime after it is online
22:16 < fantasai> then we archive a version that matches the version sent to the printer
22:16 < fantasai> but keep a dynamic version as the principal version
22:16 < fantasai> the advantage of having electronic documentation is that we can fix it as we find mistakes
22:17 < fantasai> the fact that a printed version doesn't change isn't a feature, it's a limitation
22:17 < fantasai> the user will want the most correct information
22:17 < fantasai> and *does* *not* *care* about errata
22:17 < dwx> okay
22:18 < fantasai> nobody looks at errata anyway
22:18 < fantasai> even I don't, when I'm looking things up in CSS2...
22:18 < fantasai> (which is bad, I'll admit..)
22:18 < fantasai> i look at it as an afterthought sometimes..
22:29  * fantasai looks up mod_rewrite
22:30 < fantasai> ok, I think we can do the internal redirect thing
22:30 < fantasai> got any further comments?
22:31 < dwx> version-less doc?
22:31 < fantasai> like?
22:31 < dwx> Sometimes you want to update the doc instead of creating a new one
22:32 < fantasai> right
22:32 < fantasai> we're not creating a new doc any time someone changes the file...
22:32 < dwx> For example, for FAQ, you may want to add an entry and label it [1.4 +]
22:32 < fantasai> hmmm
22:33 < fantasai> well, if it's truly versionless, then we can put it at /support/mozilla/faq
22:33 < dwx> Say I link to Command Line Arg from FAQ, how do I do that?
22:33 < fantasai> oh
22:33 < fantasai> you'd have to link to all of them........
22:34 < fantasai> either that or put the faq with the version numbers
22:34 < fantasai> /support/mozilla/1.6/faq
22:34 < dwx> hmm...
22:34 < dwx> and how would people link from outside of mozilla.org?
22:35 -!- rj_keller [~rlk@d53-80-158.nap.wideopenwest.com] has joined #documentation
22:35 < fantasai> I see what you mean
22:35 < dwx> . /supoort/mozilla/latest/faq/?
22:35 < fantasai> I was just thinking  that :)
22:35 < fantasai> sounds reasonable
22:36 < fantasai> we can have latest redirect to whatever version it is
22:37 < fantasai> the documentation for web developers, btw, would have to be organized differently
22:37 < fantasai> because they will want to know how a given thing works for all versions
22:37 < dwx> fantasai, then we also want to link to older versions from the latest version doc also
22:37 < fantasai> yeah
22:38 < fantasai> users, though, only care about the version they're using
22:38 < dwx> fantasai, and old docs? should we link to later version too?
22:38 < fantasai> no
22:38 < dwx> okay
22:38 < fantasai> because if you're looking at an old doc, you probably want that version
22:38 < fantasai> :)
22:39 < fantasai> I think it would only make sense to do the versions-link-list from /latest
22:39 < fantasai> although
22:39 < dwx> hi, RJ Keller
22:39 < fantasai> I don't think I'd do it right away 'coz that requires some time to write a script to do it
22:39 < fantasai> :)
22:40 < dwx> fantasai, we can do it manually
22:40 < dwx> for example, we might rename docs when we update it
22:40 < rj_keller> dwx: hi daniel.
22:41 < fantasai> dwx: that would require keeping two copies of, for example, comand-line-args
22:41 < fantasai> one in the 1.7 directory
22:41 < fantasai> and one in the latest directory
22:42 < dwx> no, I think latest/ should automatically redirects to 1.7/
22:42 < fantasai> yeah
22:42 < fantasai> but then the versions list would be in the 1.7 doc
22:42 < dwx> fantasai, do you log this message? Maybe sent it to RJ for him to catch up?
22:42 < fantasai> do we really want it there?
22:43 < fantasai> yes, sure