Re: Meaning of "getting started"

[Shaun McCance <shaunm gnome org>]

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.]

--
Shaun