Rewrite the Evolution User Documentation

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

Contents

Rewrite the Evolution User Documentation

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

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>
- Conditional processing (move docu to separate packages and only display if installed)?: http://mail.gnome.org/archives/gnome-doc-list/2011-May/msg00015.html and check banshee and banshee-community-extensions (<link type="guide" xref="index#extensions"/> in the "index" page of the extension)

Make developers fix bugs

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

https://bugzilla.gnome.org/buglist.cgi?bug_id=340614,655485,655519,655629,655666,655669,655494,655492,655702,655021,657233
some "Help" buttons are context sensitive, andre waiting for patch review by chen

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.