On Fri, Oct 31, 2008 at 15:07, Shaun McCance <[EMAIL PROTECTED]> wrote: > On Fri, 2008-10-31 at 13:11 +0000, Matthew Paul Thomas wrote: >> Leonardo Fontenelle wrote on 29/10/08 00:50: >> > >> > http://library.gnome.org/devel/gdp-style-guide/stable/infodesign-2.html.en >> > >> > What's the difference between "introduction" and "getting started"? >> >... >> >> "Getting started" probably is helpful, "Introduction" probably isn't. ;-) > > If we're talking about documentation in general, I'd say > it depends on what you're writing. "Introduction" should > be used to introduce concepts and terminology. This is, > I suspect, most useful in developer documentation. But > it could be useful as a subsection title for more complex > applications. For instance, a section on charting for a > spreadsheet manual might be served well by an introduction. > > Now, if we're talking about the first section of a typical > application help manual, then we definitely want "Getting > Started". And not just the title. A "Getting Started" > section should be a real hands-on tutorial to how to use > the application. > > If you have a "Getting Started" section that reads like > the following, you've done something wrong. > > Beanstalk is an application for collecting and counting > magic beans. Beanstalk is free software under the GPL. > Beanstalk uses [boring list of libraries users really > do not care about]. Beanstalk can be used to [list of > things you can do, without telling you how to do any of > them]. In the future, [OK, stop. Documentation is not > the right place for your roadmap. Ever. Seriously.]
Well, it seems that "introduction" should never be replaced by "getting started", but I think the opposite doesn't look so bad (i.e., replacing "getting started" by "introduction"). Pedro _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
