The Seventh Report: Polishing up the Cheese documentation

Hi, this time I want to share the last things I did to polish up my Cheese doc for pending items and (I hope) success the formal review.

Review comments:

First, I corrected some things that Phil, my mentor, suggested:

1. Check the XML validation errors by running ‘yelp-check validate .’

[yulys@yulys ~]$ cd cheese-docs/
[yulys@yulys cheese-docs]$ yelp .
/home/yulys/cheese-docs/photo-account.page:29: parser error : Opening and ending tag mismatch: p line 29 and item
    <item><p>You may unlock the User Account windows.</item></p>
                                                            ^
/home/yulys/cheese-docs/photo-account.page:29: parser error : Opening and ending tag mismatch: item line 29 and p
    <item><p>You may unlock the User Account windows.</item></p>
                                                                ^
/home/yulys/cheese-docs/newindex.page:50: parser error : Premature end of data in tag page line 1

^
[yulys@yulys cheese-docs]$ gedit photo-account.page
[yulys@yulys cheese-docs]$ gedit index.page
[yulys@yulys cheese-docs]$ yelp .
[yulys@yulys cheese-docs]$

* If you see errors like “Expecting element section, got comment”, that means that you have a <comment> block at the top of the page. <comment> blocks must always be at the bottom of the page,  just before the </page> tag. Other errors include failure to provide an “xref” attribute for a <link> tag (“element link: Relax-NG validity error”), and getting closing tags the wrong way around (it should be </p></item>, not </item></p>).

2. Try not to use the word “Cheese” so often. The reader knows that they are looking at the Cheese help, so descriptions like “Save a photo with Cheese” aren’t necessary. When you write a description (<desc>) for a page, don’t duplicate the title of the page; e.g. “Save a Photo” has the description “Save a photo with Cheese”. The description should always provide some additional useful information about the topic. Usually, this means explaining the point of the topic a bit better (“Save a photo that you took so you can look at it later”) or providing very quick instructions on how to complete the topic (“Right-click the photo and click <gui>Save As</gui>”).

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="save-photo">
  <info>
    <link type="guide" xref="index#photo"/>
    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Save a photo that you took so you can look at it later.</desc>
  </info>

  <title>Save a Photo</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to set the photo-mode. By the end of this page,
    the reader will be able to save a photo.</p>
  </comment>

  <p>All the photos you have taken are saving by default in the <file>Webcam</file> folder, inside the <file>Picture</file> folder. But, if you want to save your photo to an alternate location:</p>

  <steps>
    <item><p>Find the photo that you wish to save in the photo stream. </p></item>
    <item><p>Right click on it and select <gui>Save As</gui> from the pop-up menu. </p></item>
  </steps>
  <p>This will bring up a standard Save File window that will allow you to save it to a new location as well as rename it if you so wish to do. </p>
</page>

3. Notes can get in the way, and often distract the user from the main text. There are some occasions when you might need them, though.

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="take-photo">
  <info>
    <link type="guide" xref="index#photo"/>
    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Click of a button or the shortcut key to take a single photo.</desc>
  </info>

  <title>Take a Photo</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to set the Photo mode. By the end of this page,the reader will be able to take a single photo.</p>
  </comment>

  <p>You can take a photo if you are using the <link xref="index#photo-mode"/> and doing one of these alternatives:</p>

  <steps>
    <item><p>Click 'Take a Photo' which is located in the middle down of the Cheese window.</p></item>
    <item><p>Press the <key>spacebar</key> key.</p></item>
    <item><p>Use the webcam capture button, if your webcam has one.</p></item>
  </steps>

  <p>You will then see Cheese count down from three to one or instantly take the photo, depending on your <link xref="index#advanced"/>
  When the photo will appear in the photo stream at the bottom of the Cheese window.</p>

  <note><p>Press <key>Esc</key> key if you want to cancel <link xref="take-photo"/> during the countdown.</p></note>

</page>

4. Remember to use mark-up tags for buttons, labels and keys, and don’t refer to it as a “button” (or whatever) unless you absolutely have to. For example, in “Record a video”, you write “Press the Spacebar key”. It is better to write “Press<key>Space</key>.” In the same topic, you would write “Click<gui>Record a Video</gui>.” rather than “Press the ‘Record a Video’ button.” The user doesn’t need to know it’s a button.

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="record-video">
  <info>
    <revision version="0.1" date="2011-07-09" status="stub"/>
    <link type="guide" xref="index#video"/>
    <credit type="author copyright">
      <name>Julita Inca</name>
      <email>yrazes@gmail.com</email>
      <years>2011</years>
    </credit>

    <desc>Capture moments by recording a video. </desc>
  </info>

  <title>Record a Video</title>

  <comment>
    <cite date="2011-07-09" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to start the video mode. By the end of this page,
    the reader will be able to record a video.</p>
  </comment>

  <p>If you want to record a video, make sure that you are using the <link xref="video-mode"/> and follow one of these alternatives: </p>

  <steps>
    <item><p>Click <gui>Record a Video</gui> button.</p></item>
    <item><p>Press the <key>Spacebar</key> key.</p></item>
    <item><p>Use the webcam capture button, if your webcam has one. </p></item>
  </steps>

</page>

5. We have a style convention on what you do with buttons and keys. If it’s a button, say “Click <gui>Button Name</gui>.” If it’s a key, say “Press <key>Key Name</key>”. Don’t say “Press<gui>Button Name</gui>”.

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="photo-mode">
  <info>
    <link type="guide" xref="index#photo"/>

    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Activate the photo mode using Cheese.</desc>
  </info>

  <title>Photo Mode</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to start the <app>Cheese</app> application.  By the end of this page,
    the reader will be able to set the Photo mode.</p>
  </comment>

  <p>You can get the 'Photo Mode' available in Cheese if you have a webcam connected with your computer or if you have a laptop with the webcam device included. Cheese starts by default with the 'Photo Mode', ready to <link xref="take-photo"/>; if not, there are some options that activate the photo mode:
</p>

  <steps>
    <item><p>Click 'Photo mode' which is showed as an icon of a single photo, located in the left side of a group of three buttons. These buttons are on the left down side of the Cheese window.</p></item>
    <item><p>From the Cheese window, choose Cheese ▸ Photo.</p></item>
    <item><p>After pressing <gui>Take a Photo</gui> button or the <key>Spacebar</key> key.</p></item>
  </steps>

</page>

6. In “Record a video”, you used a <steps> list. Only use these for procedures that you user should follow in a set order. If it’s a list of options and the order doesn’t matter, use <list> instead. This will display as bullet points.

7. Just a small note on directions. Instead of “left down side” you would say “lower left”. * I think “Burst Mode” needs a simple example. e.g. “For example, you could use Burst Mode to take one photo per second for five seconds to capture several different expressions on your face.”

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="burst-mode">
  <info>
    <link type="guide" xref="index#burst"/>

    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Use the Burst Mode to capture several different expressions on your face in one click.".</desc>
  </info>

  <title>Burst Mode</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to start the Cheese application. By the end of this page,the reader will be able to set the Burst mode.</p>
  </comment>

  <p>If you want to take more than one picture over some time you can use the burst mode. You can get this if you have a webcam connected with your computer or if you have a laptop with the webcam device included. Cheese starts by default with the <link xref="index#photo-mode"/>, ready to <link xref="take-photo"/>; so, there are some options that activate the photo burst mode: </p>

  <steps>
    <item><p>Click <gui>Photo Burst Mode</gui> which is showed as an icon of multiple photos, located in the right side of a group of three buttons. This group of buttons are on the lower left of the Cheese window.</p></item>
    <item><p>From the Cheese window, choose Cheese ▸ Burst.</p></item>
    <item><p>After pressing <link xref="multiple-photos"/> button or the <key>Spacebar</key> key.</p></item>
  </steps>

</page>

8. Try to avoid technical words like “dialog”. Use “window” instead.

<page xmlns="http://projectmallard.org/1.0/"      type="topic" style="task"      id="video-mode">  <info>    <link type="guide" xref="index#video"/>    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Activate the video mode using Cheese.</desc>  </info>

  <title>Video Mode</title>

  <comment>    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>    <p>This assumes the reader knows how to start the Cheese application. By the end of this page,    the reader will be able to set the Video mode.</p>  </comment>

  <p>You can get the <gui>Video Mode</gui> available in Cheese if you have a webcam connected with your computer or if you have a laptop with the webcam device included. Cheese starts by default with the <link xref="photo-mode"/>, ready to <link xref="take-photo"/>; so, there are some options that activate the video mode:</p>

  <steps>    <item><p>Click <gui>Video Mode</gui> which is showed as an icon of a film roll, located in the middle of a group of three buttons. These buttons are on the left down side of the Cheese window.</p></item>    <item><p>From the Cheese window, choose Cheese ▸ Video.</p></item>    <item><p>After click <gui>Start Recording</gui> button or the <key>Spacebar</key> key.</p></item>  </steps>

</page>

9. In the “Resolution Photo” topic, perhaps you should briefly explain what resolution means, since it’s a technical term. Maybe something like “The resolution of a photo or video tells you how detailed it is. The higher the resolution, the more details you should be able to see. Higher resolution photos and videos take up more space on your hard disk.”

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="resolution-photo">
  <info>
    <link type="guide" xref="index#photo"/>
    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>Set the resolution of your photo.</desc>
  </info>

  <title>Resolution Photo</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to set the photo mode. By the end of this page,
    the reader will be able to set the resolution of your photo.</p>
  </comment>


  <p>The resolution of a photo or video tells you how detailed it is. The higher the resolution, the more details you should be able to see.</p> 
  <p>If you have more than one webcam or video device attached to your system, you can configurate what resolution the image should have:</p>

  <steps>
    <item><p>Go to Edit▸ Preferences</p></item>
    <item><p>See the Photo resolution option in the Webcam space.</p></item>
    <item><p>Choose the resolution you prefer from the drop-down list.</p></item>
  </steps>

  <note><p>Higher resolution photos and videos take up more space on your hard disk.</p></note>
</page>

10. For the names of folders, use <file>. For example, in save-photo.page, you write “the ‘Picture’ folder”. You should use “the <file>Picture</file> folder” instead.

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="view-photo">
  <info>
    <link type="guide" xref="index#photo"/>
    <revision version="0.1" date="2011-07-06" status="stub"/>

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

    <desc>View the photo after you took it. </desc>
  </info>

  <title>View a Photo</title>

  <comment>
    <cite date="2011-07-06" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to set the photo mode. By the end of this page,
    the reader will be able to view all the photos he or she took.</p>
  </comment>

  <p>You can view a photo that has been taken doing one of these steps:</p>

  <steps>
    <item><p>Locate it in the photo stream and double click on the photo you want to view.</p></item>
    <item><p>Right-click on it and select Open. This will then open the file in the default application for that file type.</p></item>
    <item><p>Search inside the <file>Picture</file> folder, and find the <file>Webcam</file> folder.</p></item>
  </steps>

</page>

What was left?

1. Delete the ‘-section’of the index.page of the different sections I declared.

  <section id="photo" style="2column">
    <title>Photo</title>
  </section>

  <section id="video" style="2column">
    <title>Video</title>
  </section>

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

  <section id="effects" style="2column">
    <title>Effects</title>
  </section>

  <section id="advanced" style="2column">
    <title>Advanced Settings</title>
  </section>

  <section id="problems">
    <title>Common Problems</title>
  </section>

* You have to check all the related files with this ‘-section’ part, grep command was useful:

[yulys@yulys cheese-docs]$ grep -section *.page
delay-photos.page: <link type="guide" xref="index#burst-section"/>
multiple-photos.page:    <link type="guide" xref="index#burst-section"/>
number-photos.page: <link type="guide" xref="index#burst-section"/>
photo-account.page:    <link type="guide" xref="index#photo-section"/>
resolution-photo.page:    <link type="guide" xref="index#photo-section"/>
take-photo.page:    <link type="guide" xref="index#photo-section"/>...

2. Complete the documentation of the burst mode,  effects and advanced settings and their respective pages. e.g. number of photos:

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="number-photos">
  <info>
    <revision version="0.1" date="2011-07-09" status="stub"/>
 <link type="guide" xref="index#burst"/>
    <credit type="author copyright">
      <name>Julita Inca</name>
      <email>yrazes@gmail.com</email>
      <years>2011</years>
    </credit>

    <desc>Set the quantity of photos you want to take using the burst mode.</desc>
  </info>

  <title>Number of Photos</title>

  <comment>
    <cite date="2011-07-09" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to start the burst-mode. By the end of this page,
    the reader will be able to set the number of photos when he or she will take multiple photos.</p>
  </comment>

  <p>If you are going to take multiple photos, maybe you want to set the number of them.
You can modify this parameter by doing:</p>

  <steps>
    <item><p>Click Edit▸Preferences.</p></item>
    <item><p>Write the number you desire or choose the number from the down drop list of the <gui>Burst Mode</gui> section.</p></item>
    <item><p>Close the <gui>Preferences</gui> windows, changes will be automatic saved.</p></item>
  </steps>

</page>

what else…

1. I think the link xref have to be included in parts like the photo mode, since I mentioned the ‘Take a photo’ option, which has details in other page.

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="introduction">

  <info>
    <link type="guide" xref="index"/>
    <revision version="0.1" date="2011-07-09" status="stub"/>

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

    <desc>Introduction to the <app>Cheese Webcam Booth.</app></desc>
  </info>

  <title>Introduction</title>

  <comment>
    <cite date="2011-07-09" href="mailto:yrazes@gmail.com">Julita Inca</cite>
    <p>This assumes the reader knows how to connect the webcam. By the end of this page, the reader will be able to use Cheese.</p>
  </comment>

  <p>Cheese is a webcam booth application for the Gnome Desktop. It allows you to take a photo, record a video, and take multiples photos in burst mode while you either are sitting or standing in front of your computer, alone, with your family, friends or pets.</p>  

  <p>Cheese includes 'Effects' that add special, fancy and funny effects in your pictures and videos, wherever you and your computer are.
By using Cheese, you can get awesome and original photos and videos that you can easily search through your files and share with others. </p>

  <steps>
    <item><p>Open the <app>Cheese</app> application from the <gui>Activities</gui> overview.</p></item>
    <item><p>Cheese starts by default with the 'Photo Mode', ready to 'Take a Photo'.</p></item>
    <item><p>Enjoy your new photos and videos: <link xref="take-photo">, <link xref="record-video"> or <link xref="multiple-photos">.</p></item>
  </steps>
</page>

2. Describe each effect with additional pictures. I chose them carefully and I made a collage.

Bulge .- Fits any part of your face or anything you want in a central sphere photo/video area to make it looks as a hump or bulge.

http://live.gnome.org/GnomeVideoEffects/Effects

3. Describe the properties image with additional pictures. Because of my skunked eyes I exposed my sleepy teddy bear and he did the model job for me

e.g. Brightness.- The more you illuminate the quality of the image, your photo/video comes out as lighter than a regular photo. The opposite happens if you adjust less brightness until get a complete white chart of your image when brightness is at maximum value and black chart when brightness is at zero.

***************************************************************************************

[yulys@yulys cheese-docs]$ git commit -a
[master 761997b] Correcting some details and adding some features to the Cheese documentation.
 31 files changed, 167 insertions(+), 228 deletions(-)
 rename save-video.page => delete-video.page (52%)
 delete mode 100644 effects.page
 delete mode 100644 no-effect.page
 rewrite save-video.page (60%)
[yulys@yulys cheese-docs]$ yelp-check validate .
[yulys@yulys cheese-docs]$ git push origin master
Counting objects: 59, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (31/31), done.
Writing objects: 100% (31/31), 7.70 KiB, done.
Total 31 (delta 26), reused 0 (delta 0)
=> Syncing Gitorious... [OK]
To git@gitorious.org:cheese-docs/cheese-docs.git
   ee4e503..761997b  master -> master
[yulys@yulys cheese-docs]$

********************************************************************************

-> Useful sources related to the cheese project:

http://effectv.sourceforge.net

http://git.gnome.org/browse/empathy/tree/help/C

http://gstreamer.freedesktop.org/ http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/images/gstreamer-overview.png http://gstreamer.freedesktop.org/documentation/plugins.html http://opencv.willowgarage.com/wiki/

About these ads

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, Catedrático USIL desde el 2013, Especialista IT en IBM desde el 2013, con certificaciones en AIX 6.1 e ITIL, a simple mortal, like you!
This entry was posted in GNOME and tagged , , , , , , . Bookmark the permalink.

2 Responses to The Seventh Report: Polishing up the Cheese documentation

  1. A very nice write-up of good practices; thanks for that!

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