Rewrite the Evolution User Documentation

/!\ The new documentation has been merged. See the results!

Contents

  1. Rewrite the Evolution User Documentation
    1. Why?
    2. Who?
    3. How?
    4. Where?
    5. Getting involved
    6. Plans
      1. For version 3.3
      2. Potential future
      3. Make developers fix bugs
    7. Historical (archived) steps for merging the docs from gitorious.org into git.gnome.org

Last update: September 29th, 2011

Why?

  • The old documentation was huge, not of high quality, contained redundant information and marketing buzz, had strange wording and missing consistency in terminology, missed proper markup information, was a PITA to translate, did not cover the real problems that users out there have (those were partially in the FAQ which was used for the new docs), and was not task-oriented.

Who?

How?

  • Using Mallard: Task oriented help instead of describing the user interface.

  • Get the new help pages (see "Getting involved" section below) and work on whatever you want. This can be:
    • Create help pages from relevant FAQ entries
    • Fix TODOs in existing help pages (see below)
    • Create new pages on topics that interest you. Just go ahead - we can rename, move and sort anything out later.
    • In case this all becomes too complex we could also list all existing and yet-to-create help pages in a table on this wikipage and everybody can set her/himself as assignee?

  • Don't blindly reuse the old manual or existing screenshots but reflect whether they provide a value additional to the help text. Note that Novell was kind enough to relicense the old manual so we can reuse the few useful parts. If you re-use content from the old manual you MUST list "Novell, Inc" as an author like this: 

 <credit type="author">
   <name>Novell, Inc</name> <!-- Content partially from http://library.gnome.org/users/evolution/2.32/add-the-exact-url-here -->
 </credit>

  • Please use TODO: (in this exact spelling) in comments in help pages to mark and potentially outline additional work/changes needed to a page or section. To find TODO comments in your local checkout directory, you can run grep -r TODO . (yes, with the dot at the end).

    • Use TODO:POST-3-2: for stuff to investigate after 3.2 release, and TODO:DEVELOPERS: for stuff that needs input from developers first

  • Where it makes sense, please try to use prefixes for the file names of the help pages so we don't lose overview when this has become big with hundreds of files. Please see the names of existing help pages to get an idea.
  • Please try to avoid phrases in the page title or desc like "How to ...", "Explains ...", "A short introduction on" etc.
  • If somehow possible, please try to include words with very similar meanings in the page desc for the sake of better finding (for example: Spam-Junk, Delete-Remove).

  • Maybe I'm too picky now, but I (AndreKlapper) prefer the uncountable plural "mail" to "email". "Message(s)" can be used for countable cases.

  • From https://lleksah.wordpress.com/2011/07/17/the-seventh-report-polishing-up-the-cheese-documentation/ :

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

    • For the names of folders, use "<file>Foldername</file>".

    • For Buttons, use "Click <gui>Button Name</gui>." If it’s a key, say "Press <key>Key Name</key>". Don’t say "Press<gui>Button Name</gui>".

  • See http://blogs.gnome.org/aklapper/2010/12/16/evolution-user-documentation-in-mallard/ for a potential rough concept of categorization.

Where?

Development takes place in GNOME Git.

Getting involved

Contact us (see "Who?" section for links with contact information).

Technical information if you plan to contribute:

  • If you are a registered GNOME developer, run git clone ssh://youraccountname@git.gnome.org/git/jhbuild which will create the folder evolution. The help files are in the subdirectory help.

  • If you are NOT a registered GNOME developer, run git clone git://git.gnome.org/git/jhbuild which will create the folder evolution. The help files are in the subdirectory help.

  • Edit the files that you want to edit. Make sure that you are listed in the Authors section of each file that you worked on.

  • To see the results of your changes in Yelp (GNOME's help browser), in the local checkout folder, run yelp . (yes, with the dot at the end).

  • If you have commit access to GNOME's git server:

    • Only if you have created a new file, run git add filename to register the file in git.

    • To register your changes locally in your git checkout, run git commit -a (to commit all changes) or git commit filename1.page filename2.page to commit specific changes in some files.

    • To share your changes with others, run git push so the updated files will be sent upstream to the server at gitorious.org.

  • If you don't have commit access to GNOME's git server:

    • Run git diff > filename and attach the file called filename to a bug report in GNOME's Bugzilla.

Plans

  • In general: When adding or removing pages do not forget to update the list in help/Makefile.am!

For version 3.3

  • Go through the remaining "TODO"s in the files by running grep -r TODO . (yes, with the dot at the end)

  • Fix open bug reports when applicable.

Potential future

  • maybe explain the "Image Gallery" option in mail composer (need input from developers)
  • Cover additional package evolution-rss?
  • printing? not worth it, same as everywhere!

  • File > Forget Passwords? Kills really everything, better to not advertise it IMO - document after https://bugzilla.gnome.org/show_bug.cgi?id=660438 has been fixed

  • Cover IM/Pidgin syncing under Edit > Prefs > Mail Prefs > IM Contacts, however I'd really prefer Empathy support here first before advertising it

  • Consistency checks:
    • Capitalization of title!
    • Message vs mail vs email

  • Use <element its:translate="no">foo</element> for stuff that should not be translatable, but must define xmlns:its somewhere - <shaunm> xmlns:its="http://www.w3.org/2005/11/its" on the <p> or any element above it. I usually just define all my namespaces on <page>

Make developers fix bugs

In order to have sane user docs some UI flaws should get fixed by developers first:

Historical (archived) steps for merging the docs from gitorious.org into git.gnome.org

  • Fix all markup errors (I failed, see this commit

  • Remove old FAQ menu item in http://git.gnome.org/browse/evolution/commit/?id=ce6f467e3e139926d3a4241429a0f2e9fcbf3294 and http://git.gnome.org/browse/evolution/commit/?id=0807b988ddbc2e91c54ad20cbd3d4fdef1021244

  • Validate!: http://mimico-tiffany.tumblr.com/post/25656871782

  • Redirect online FAQ at http://live.gnome.org/Evolution/FAQ to library.gnome.org

  • cd git-gnome/evolution/help/C/
  • git rm evolution.xml
  • cd figures
  • git rm *.png
  • cd ..
  • copy files from gitorious to evolution/help/C/
  • git add *.page figures figures/*
  • cd ..
  • edit /help/Makefile.am
  • git commit -m "Put new user documentation in place" -a
  • Merge old doc translations:

    • WARNING: Make sure that no license conflicts between new docs under CC and translations under GFDL are in place! (Example)

    • xml2po -o newids.pot ./C/*.page
    • Languages to run the following commands for (replace xy by the language code) are listed in old Makefile.am

    • add those strings where msgid=msgstr to xy/xy.po (gedit ./*/*.po) as I'm too lazy to test <foo its:translate="no">bar</foo>

    • msgmerge --compendium=../po/xy.po -o mergedlang.po xy/xy.po newids.pot (with ../po/cs.po the current user-interface.po)
    • check statistics by msgfmt -c --statistics -o delete.mo mergedlang.po
    • mv mergedlang.po ./xy/xy.po
    • repeat this for each language
    • rm newids.pot
    • rm delete.mo
    • git commit -m "Merge old translations for new user docs" -a

  • update instructions on https://live.gnome.org/Evolution/DocRewrite for new git location.

  • Announce to gnome-i18n, gnome-doc-list, evolution-list
  • Still to do: Fix context sensitive help button linking in Evolution (grep for "e_display_help" and "help_section"?) -- chen; email sent

  • Still to do: Useful <note> styles, like tip, warning, important.

Apps/Evolution/DocRewrite (last edited 2013-08-08 22:50:12 by WilliamJonMcCann)