The Document Foundation Wiki
 

Documentation/Production

From The Document Foundation Wiki

Jump to: navigation, search


Contents

Discussion List for Documentation

documentation@global.libreoffice.org: Group for people working on LibreOffice documentation and help system

Subscription: documentation+subscribe@global.libreoffice.org

Digest subscription: documentation+subscribe-digest@global.libreoffice.org

Archives (old): http://www.libreoffice.org/lists/documentation/
Archives (new): http://listarchives.libreoffice.org/global/documentation/

Mail-Archive.com (old): http://www.mail-archive.com/documentation@libreoffice.org/
Mail-Archive.com (new): http://www.mail-archive.com/documentation@global.libreoffice.org/

GMANE (old): http://dir.gmane.org/gmane.comp.documentfoundation.libreoffice.documentation
GMANE (new): http://dir.gmane.org/gmane.comp.documentfoundation.libreoffice.global.documentation


Task List for User Guides

Update user guides

The chapters in the user guides need to be updated for LibreOffice 3.4.

See the Documentation Development page for the status of chapters and what needs to be done.

Proposals for user guide revision

Proposal for Major Revision of Getting Started Guide

Proposal for Major Revision of Writer Guide

Wish List for User Documentation

Please list here the things you would like to see provided as user documentation. Obviously we can't do everything unless we have enough people to do the work, but it's good to have a "wish list" -- someone might see one of the items and say "I can do that!"

Offer from Friends of OpenDocument re printed copies

Friends of OpenDocument, Inc (FoOD for short), an Australia-based not-for-profit association, has offered to produce printed copies of the user guides for LibreOffice.

TDF is, of course, welcome to set up its own account at Lulu or Lightning Source or elsewhere, instead of using FoOD's services.

Wish List for Developer Documentation

Please list here the things you would like to see provided as developer documentation.

  A few diagrams of the object model hierarchy would help newcomers get started faster.  


Workflow

(Added by Jean Hollis Weber)

Here is what I want to see. I don't care what s/w is used, as long as I can track development easily and without ambiguity.

Preamble

Best source doc filetype is ODT because it is the easiest to use for high-quality output to a variety of other formats (PDF, wiki, ePub, HTML, whatever).

Must be able to track dates, file versions, & status. Separate folders work and are easy for everyone to see what's at which stage of development. Changing the filename at each stage to show date and initials also makes it easy to everyone to see what's going on. That's a bit low-tech, but it works... including when the files have been downloaded to someone's computer. No accidental overwriting, easy to tell which file is what.

Someone must be able to over-ride "checkout" if the person who checks out a file doesn't return it in a reasonable time and doesn't respond to requests for status updates or unlocking of the file. This happens all the time but should not be allowed to stall work on a book.

Workflow

1) Create draft doc, upload to Drafts folder, mark as ready for review.
2) Reviewer checks out draft doc, makes changes with tracking on, uploads result to Feedback.
3) Author (or someone else, depending on book & circumstances) revises draft, removes change tracking up to that point, replaces file in Drafts & marks as ready for review.
4) Repeat 2 & 3 as needed.
5) When ready, author (or other) puts file into Copyediting/Proofing & marks as ready for editing.
6) Copyeditor does job with change tracking on, puts into Feedback.
7) Author (or other) accepts/rejects edits, puts file into Indexing/Final Layout folder, marks as ready for further work.
8) Indexer/Book Coordinator/whoever final checks all and puts file into Published folder (or returns to Feedback for further work).
9) Book Coordinator/Publisher/whoever outputs file into various formats (PDF, others to be decided) and makes available to public, with a copy
into the working folder for next revision.

People Needed

In addition to volunteer writers, reviewers, editors, indexers, researchers etc., we need some people to help coordinate and mentor volunteers.

Documentation Coordinators

People are needed to take responsibility for specific documentation projects. This doesn't mean you have to do all the work! But you do need to commit time to coordinating volunteers doing smaller pieces of the work, keep track of what need to be done, who is doing what, what's on time or behind schedule or not getting done at all (for example, when updating a book to the latest version of the software). Jean Weber has been doing most of this at OOoAuthors, but she can't keep up with everything.

Mentors

People are also needed to help others get started and also help them with general technical writing issues. We get a lot of volunteers who want to improve their technical writing skills, but we don't have enough mentors to help them.

Conference Call

The date/time of the first documentation conference call is Saturday, 27 November 2010, 11 pm CET. You can do time conversions here: http://doodle.com/qq8hiysi36fhkwy4

Conference call wiki page for more info and the agenda (feel free to add stuff, but there's quite a list already):
http://wiki.documentfoundation.org/Documentation/ConfCalls


Sample screenshots

(Added by Jean Hollis Weber, 9 November 2011.)

After upgrading to Ubuntu 11.10, I have been unable to get the "XP Silver" theme installed, possibly because this version of Ubuntu uses Gnome 3, not Gnome 2.

I have found what I consider an acceptable replacement theme, a combination of an GTK+ theme called "Adwaita" (shipped with Ubuntu 11.10) and a Window theme called Evolve, which must be downloaded and installed (instructions below). Note that using the Evolve GTK+ theme does not give the desired result (the contrast is not good enough).

Below is an example screenshot.

Sample of Adwaita + Evolve theme

To install the Evolve theme, follow the instructions on this page: http://browse.deviantart.com/customization/skins/linuxutil/desktopenv/gnome/gtk3/#/d4dn66o.

Ubuntu 11.10 users can install it using the commands below,

sudo add-apt-repository ppa:webupd8team/themes
sudo apt-get update
sudo apt-get install evolve-gtk-theme

Now install the Gnome Tweak Tool:

sudo apt-get install gnome-tweak-tool

This creates an app called "Advanced Settings". Open that and (a) if necessary, select Adwaita as the GTK+ theme; and (b) change the Windows theme to Evolve.


IN ADDITION to setting up the theme described above, you need to select the Galaxy icon set in LibreOffice. (This is not a Ubuntu icon set. This is a LibreOffice icon set.)

The choice of the LO icon set is found in Tools > Options >LibreOffice > View; in the User Interface section of that page, under Icon size and style, choose Galaxy (default).


(Older notes, added by Jean Hollis Weber, 17 June 2011.)

NOTE: The user guides in English are using the "XP Silver" theme. Other language groups may use Clearlooks or some other them.

Below are two sets of screenshots, for comparison. Both were taken from the same document on Ubuntu 11.04. One set (with the blue title bars) uses the Clearlooks theme; the other (all gray) uses the XP-Silver theme developed by Michele Zarri for the OpenOffice.org user guides.

Important criteria for screenshots in the user guides include high contrast between the text and background in all parts of the screenshot, and high quality printing in black and white (mainly for printed copies available through Lulu, but also for anyone printing from the PDFs). I have recommended using the XP-Silver theme for the user guides, but this is open for discussion.

You can download the XP-Silver theme here. It is a zip file containing instructions and two other files.

Sample 1: Clearlooks theme
Sample 1: XP Silver theme
Sample 2: Clearlooks theme
Sample 2: XP Silver theme
Personal tools
Namespaces
Variants
Actions
Wiki
Navigation
Toolbox
donate