source: trunk/doc/src/docbook/userdoc/overview.xml @ 5684

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: overview.xml 5684 2011-08-02 15:00:19Z nicklas $
  
  Copyright (C) 2007 Nicklas Nordborg, Martin
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="userdoc_overview" chunked="0">
  <?dbhtml dir="overview"?>
  <title>Overview of user documentation</title>
  <para> The 'User documentation' part is quite extensive and covers everything from how to Log in on
    a BASE server and find your way through the program, to working with experiments and doing some
    useful analysis. The intention with this chapter is to give an overview of the following chapters
    so it will be easier for you to know where to look for certain information in case you don't want
    to read the whole part from the beginning to the end.</para>
  <sect1 id="userdoc_overview.environment">
    <title>Working environment</title>
    <para> Before you start working with any big experiment or project in BASE it could be a good idea
      to get to know the environment and perhaps personalize some behavior and appearance of the
      program. When this is done your daily work in BASE will be much easier and you will feel more
      comfortable working with the program.</para>
    <para>
      Most of the things that have to do with the working environment are gathered in one chapter,
      where the first subsection,
      <xref linkend="webclient.introduction" />
      , gives a good guidance how to start using BASE including a general explanation how to navigate
      your way through the program.
    </para>
    <para>
      The second subsection,
      <xref linkend="webclient.configuration" />
      , describes how to personalize BASE with contact information, preferences and changing password.
      The preferences are for instance some appearance like date format, text size or the look of the
      toolbar buttons.
    </para>
    <para>
      The last two subsections,
      <xref linkend="webclient.items" />
      and
      <xref linkend="webclient.itemlist" />
      , in the web client chapter explains how to work with BASE. No matter what you are going to do the
      user interface contains a lot of common functions that works the same everywhere. For example,
      how to list and search for items, how to create new items and modify and delete existing items.
      Subsequent chapters with detailed information about each type of item will usually not include
      descriptions of the common functionality.
    </para>
  </sect1>
  <sect1 id="userdoc_overview.start2work">
    <title>Start working with BASE</title>
    <para>
      There are some working principles that need to be understood by all users in BASE. These concern
      the permission system and how to get the workflow to move on without any disturbance caused by
      insufficient permissions. The key is to work in projects, which is covered in detail in
      <xref linkend="project_permission" />
      .
    </para>
    <para> 
      Understanding the permission system and how to work in projects will not only make it more
      simple for you to work in BASE but also for your co-workers who want access to your data.
    </para>
    <para>
      The next thing to do is to add some relevant data to work with. Most of the different items can
      be created manually from the web client, but some items and data must be imported from files.
      Before importing a file, it has to be uploaded on the BASE-server's file system.
      <xref linkend="file_system" />
      gives you information about the server's file system and how to upload the files.
    </para>
    <para>
      <xref linkend="import_data" /> explains how the import is done
      and <xref linkend="export_data" /> covers how data later on can
      be exported from the database back into files, often simple text
      files or xml files.
    </para>
    <para> 
      Each different item has it's own section in this part of the documentation, where more
      specific information and also some screen shots can be found. Go back to the table of contents
      for this part and look up the item you want to know more about.
    </para>
    
    
    <sect2 id="userdoc_overview.start2work.administrative">
      <title>Administrative tasks</title>
        <para> 
          Most of the tasks in this section require more privileges than the normal user
          credentials. As always, there are many ways to do things so steps presented here is the path
          to get going with BASE as fast as possible without creating havoc in future use of the BASE
          server.
        </para>
        <orderedlist>
          <listitem>
            <para>
              Log in as
              <prompt>root</prompt>
              using the password you set during BASE initialization. Create an account and give it the
              administrator-role. Switch user to the new admin account and use this for all future
              administrative tasks.
            </para>
            <note>
              <para> 
                The root-account should only be used to create the first administrator account and
                nothing else.
              </para>
            </note>
          </listitem>
          <listitem>
            <para> 
              First thing to do, when logged in as administrator, is to create other user-accounts
              and give them appropriate roles, most of them should be assigned to the User-role.
            </para>
            <para>
              Information related to user-accounts can be found at
              <xref linkend="user_administration" />.
            </para>
          </listitem>
          <listitem>
            <para>
              Next step for you as an administrator is to import reporter-map and corresponding reporters
              to BASE. For import of Genepix data you can use the
              <prompt>Reporter importer</prompt>
              plug-in and
              <prompt>Reporter map importer</prompt>
              plug-in that come with BASE. Go to
              <menuchoice>
                <guimenuitem>Array LIMS</guimenuitem>
                <guimenuitem>Array designs</guimenuitem>
              </menuchoice>
              or
              <menuchoice>
                <guimenuitem>View</guimenuitem>
                <guimenuitem>Reporters</guimenuitem>
              </menuchoice>
              respectively and start the import from there. You can read more about data-import in
              <xref linkend="import_data" />
            </para>
          </listitem>
        </orderedlist>
      </sect2>
      <sect2 id="userdoc_overview.start2work.user">
        <title>User tasks</title>
        <para> 
          A normal user is not allowed to add array design, reporter information, and a lot of
          other information to BASE. The reason for this is that a lot of information should only exist
          as one copy in the database. For example, reporters should only exist in one copy because
          everyone uses the same reporters. There is no need to store several copies of the same array
          design.
        </para>
        <para> 
          A user will normally upload experimental data to BASE for import into the database. To be
          able to import the data, the array design which is used, must be available in BASE at import
          time. If the array design is not available, a user with the proper credential must add the
          array design to BASE.
        </para>
        <orderedlist>
          <listitem>
            <para>
              The first thing for an user to do is creating a project to work in and set this as
              <emphasis>the active project</emphasis>.
              This should be done before any other items are created.
              <xref linkend="project_permission.projects" />
              tell you more about how working in projects can help you and your co-workers.
            </para>
          </listitem>
          <listitem>
            <para>
              Next step is to create raw bioassays and up-load raw data to BASE. This is done in the raw
              bioassay section.(
              <menuchoice>
                <guimenuitem>View</guimenuitem>
                <guimenuitem>Raw bioassays</guimenuitem>
              </menuchoice>
              ) . More information see
              <xref linkend="experiments_analysis.rawbioassay" />
            </para>
          </listitem>
          <listitem>
            <para>
              Now when there are data to work with, you can create your first experiment. You reach the
              experiment section through the menu
              <menuchoice>
                <guimenuitem>View</guimenuitem>
                <guimenuitem>Experiments</guimenuitem>
              </menuchoice>
              Further reading in
              <xref linkend="experiments_analysis.experiments" />
            </para>
          </listitem>
          <listitem>
            <orderedlist>
              <listitem>
                <para>
                  The analysis often starts with the creation of a root bioassay set. Open the recently
                  created experiment and go to the
                  <guilabel>Bioassay sets</guilabel>
                  tab. Click on the
                  <guibutton>New root bioassay set</guibutton>
                  button to start the creation.
                </para>
              </listitem>
              <listitem>
                <para>
                  With a root bioassay set you can now continue your analysis with different kinds of
                  analysis plug-in. To the right of the each listed bioassay set is a set of icons for the
                  actions that can be performed.
                  <xref linkend="experiments_analysis.analysis" />
                  goes to the bottom of analysis in BASE.
                </para>
              </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>
        <para> 
          This concludes the short step-by-step get going text. Far from all functionality in BASE
          has been covered here. E.g. nothing about LIMS or biomaterials have been mentioned. But you
          should now at least be familiar with getting to that point when it is possible to do some
          analysis.
        </para>
    </sect2>
  </sect1>
</chapter>