10th report: Documentation Cheese and Evolution from Germany!

During the Desktop Summit Berlin 2011, I spent some time doing my job: documentation.
In a few words, this is what I did:
* Re-building Cheese packages to get the last version in my Fedora15 laptop.
   Marina was the person who helped me to acomplish this task!
   Now I can take photos with effects and record videos with effects.
* Re-structuring Cheese topics, their order and make it more atractive for users.
   German Poo was the person who helped me to do this task!
Before:
Now:
<page xmlns="http://projectmallard.org/1.0/"
      type="guide" style="task"
      id="index">
  <info>
    <revision version="0.1" date="2011-06-26" status="stub"/>
    <title type="link">Cheese Webcam Booth</title>
    <title type="text">Cheese Webcam Booth</title>

    <credit type="author copyright">
      <name>Julita Inca</name>
      <email>yrazes@gmail.com</email>
      <years>2011</years>
    </credit>

    <desc>Cheese Webcam Booth</desc>
  </info>

   <title>
    <media type="image" mime="image/png" src="cheese.png" width="40" height="40">
	Cheese Webcam Booth logo
    </media>
	Cheese Webcam Booth
  </title>

  <comment>
    <cite date="2011-06-26" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to configure the webcam and the cheese application. By the end of this page,
    the reader will be able to take a photo, record a video and take multiple photos in only one click with the Cheese, which gives your photos and videos funny and fancy effects.</p>
  </comment>

  <section id="photo-video" style="2column">
    <title>Photo and Video</title>
  </section>

  <section id="burst" style="2column">
    <title>Burst's Photos</title>
  </section>

  <section id="problems">
    <title>Problems and Questions</title>
  </section>

</page>
[yulys@yulys ~]$ cd cheese-docs/
[yulys@yulys cheese-docs]$ git branch
* master
[yulys@yulys cheese-docs]$ git commit -a
[master 2760eb7] I combined photo and videos in one option and reestructured problems.
 21 files changed, 45 insertions(+), 188 deletions(-)
 delete mode 100644 mac-cheese.page
 delete mode 100644 skype-ekiga.page
 delete mode 100644 slow.page
[yulys@yulys cheese-docs]$ yelp-check validate .
[yulys@yulys cheese-docs]$ git push origin master
Counting objects: 38, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (20/20), done.
Writing objects: 100% (20/20), 3.19 KiB, done.
Total 20 (delta 18), reused 0 (delta 0)
=> Syncing Gitorious... [OK]
To git@gitorious.org:cheese-docs/cheese-docs.git
   5faf930..2760eb7  master -> master
[yulys@yulys cheese-docs]$
* Re-viweing my new Cheese structure and the whole documentation I wrote.
   Shaun McCance was the person who helped me doing some suggestions that I have to improve.
* Re-evaluating the perspective I took as a comon problems for users because I did so technical.
   Tiffany Antopolosky was the person who helped me to do this task.
*  Interaction of the Cheese Documentation with the general Desktop help Gnome 3.
    Anita Reitere was the person who helped me to check file *.page.stub  in the Desktop help.
 * I also did some reviewing of the Evolution work that Andre Klapper published on line.
    At first sight, these are my recomendations:
   – Write the introduction section, because there is no one.
   – Use infinitive instead of gerunds in verbs.
   – Try to re-structure topics in order to fit them in only one screen.
   – Try to avoid pictures or screenshot because they are harder to maintain.
   – The photo of the document is also outdated,  we have to think inothers team like “location”.
   – Try to use marketing behind the writing, we are trying to offer atractive documentation.
   – Use the simplest writing possible, we haveto convince users to use our applications.
   – Try to avoidtoo many details, we can provide our users a guide and let them growing up by theirselves.
     This means, we have to trust they can discover more details, advanced technical settings and more things.
Well, I hope my contributions can fulfill some expectations, after receiving kidness support, helpful help and cheers from many people of the Gnome comunity.  <3

About Julita Inca

Ingeniero de Sistemas UNAC, Magíster en Ciencias de la Computación PUCP, OPW GNOME 2011, Miembro de la GNOME Foundation desde el 2012, Embajadora Fedora Perú desde el 2012, ganadora del scholarship of the Linux Foundation 2012, experiencia como Admin Linux en GMD y Especialista IT en IBM, con certificaciones RHCE, RHCSA, AIX 6.1, AIX 7 Administrator e ITILv3. Experiencia académica en universidades como PUCP, USIL y UNI. HPC researcher, a simple mortal, like you!
This entry was posted in GNOME, τεχνολογια :: Technology and tagged , , , , , , , , , . Bookmark the permalink.

3 Responses to 10th report: Documentation Cheese and Evolution from Germany!

  1. aklapper says:

    > * I also did some reviewing of the Evolution work that Andre
    > Klapper published on line.
    > – Write the introduction section, because there is no one.

    I agree.

    > – Use infinitive instead of gerunds in verbs.

    Not sure about this one and your motivation.

    > – Try to re-structure topics to fit them in only one screen.

    I think that’s impossible for a complex application like Evolution. I’ve tried to keep it short but I already have three levels of abstraction (guide pages) in some areas.

    > – Try to avoid pictures or screenshot because they are harder
    > to maintain.

    That’s what I’ve done.

    > – The photo of the document is also outdated, we have to
    think inothers team like “location”.

    It is not outdated, but correct for the mailer view. However this should be clearly explained as it confused you.

    > – Try to use marketing behind the writing, we are trying to offer atractive documentation.

    After having worked on the old manual for years that was full of meaningless introduction sentences such as “Evolution helps you to…, Evolution makes it easy to…” I tried to keep focused on providing a helping hand to people in order to get their work done efficiently, however if you have concrete improvement suggestions I’m interested in them, as there can be also useful marketing of course.🙂

    > – Use the simplest writing possible, we haveto convince users to use our applications.

    I tried this in the chapters that I consider basic usage, however for advanced options I think that it is acceptable to also use a little bit of advanced speech.

    > – Try to avoidtoo many details, we can provide our users a guide and let them growing up by theirselves.

    I tried to do this via splitting sections into Basic and Advanced (e.g. Corporate) usage.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s