Entries Tagged 'Documentation' ↓

L10n & Docs at GUADEC 2014

At this year’s GUADEC, there will be a number of sessions relevant to people interested in GNOME localization and documentation:

  • On Monday, Kat will give an update from the docs team called Documentation: state of the union. Her talk will detail what has happened in the documentation realm since GUADEC 2013, so be sure to attend.
  • Team Reports on Saturday will include localization and documentation.
  • There will be a screenshot automation BoF on July 30th. Vadim Rutkovsky from Red Hat’s Desktop QE has some sweet surprise for you, translators!
  • Finally, on July 30th and 3Ist, Daiki Ueno and Alexandre Franke are planning to organize an i18n hackfest to work on translation tools, spellcheckers, dictionaries, input methods, and related fields.

I’ll be arriving tomorrow evening with Christian Schaller and other desktop people from Red Hat Czech and leaving on the 31st – hope to see you all in Strasbourg!

sponsored-badge-shadow guadec-2014-badge-large

 

Open Help Conference 2014

This is a belated post on the Open Help Conference in Cincinnati, OH that I had the chance (thanks for sponsoring me, Red Hat!) to attend this year. It took place from June 14-15 at a nice venue provided by Garfield Suites Hotel. The Conference was followed by the GNOME Docs Sprint from June 16-18.

The Open Help Conference is much smaller in attendance than some of the large industry conferences for technical writers out there. This actually allows the attendees to actively participate in many talks and discussions, similarly to what you can usually experience at unconferences. It was the Conference’s primary focus on docs communities that made attending each of the sessions very relevant to those of us who work on open source documentation.

Along with people representing other open source companies and communities (this included Eric Shepherd from Mozilla or Michael Downey from OpenMRS), there were also two fellow Red Hatters attending (Rich Bowen and David King). We had quite a few people from GNOME Docs, too. The Conference was organized by Shaun McCance who did a fantastic job running the whole event as he found time not only to take care of the venue and catering, but also of the social events on both conference days that took place in his lovely hometown of Cincinnati. Thanks again, Shaun!

You can check #openhelp and Michael Downey’s excellent notes to learn more about the different talks and sessions held at OH.

Open Help Conference 2014 Hackfest

The Open Help Conference 2014 Hackfest followed an unwritten tradition in the GNOME Documentation Project of having two GNOME docs hackfests or sprints annually. Unlike the sprint held earlier this year in Norwich, UK where the team worked mostly on updating the user help for the upcoming GNOME 3.12 release, the Cincinnati hackfest focused on finishing the GNOME System Administration Guide. We managed to completely rework the overall structure of the guide and redesigned the index page for the guide, following the earlier design mockups prepared for GNOME Help by Allan Day.

The restructured System Administration Guide now features the following main groups of topics:

  • User Settings (Lockdown, Pre-seed user defaults, Pre-seed email/calendar/groupware, Appearance, Setup)
  • Login Settings (Appearance, Session, Management)
  • Network (NetworkManager, etc.)
  • Software (Apps, Extensions, Management)
  • Troubleshooting / diagnosis

More details can be found on the Guide planning page.

Other things that caught my attention during the conference:

Duck Pages

Shaun’s plans for the future include an additional input format for Mallard-based documentation – so called Duck pages. A Duck page is essentially a plain text format based on Mallard XML that doesn’t use the often distracting XML syntax. Duck pages should make it easy to author single-sourced topic-based documentation with a Markdown or AsciiDoc-like syntax. Unlike Markdown and others, Duck pages aim to not only allow for quick creation of rich-formatted docs, but also to contain data necessary to integrate the document with the rest of your Mallard-based documents.

Blip

Shaun also presented another tool that he has been working on: Blip. It is a web application to monitor documentation projects that use SCM repositories. Some examples include:

Blip lets you not only browse through individual modules in your documentation project, but it also mines data to present information about contributors, their commit or mailing list activity, and much more.

  • An example of a project profile with complete data on branches, commits, authors, included documents, and more: Gnome User Documentation
  • An example of of a user profile with personal stats: Shaun McCance

Fedora Docs FAD 2014

The Fedora Docs team recently organized a FAD (Fedora Activity Day), with the goal to work on areas such as attracting new contributors, mentoring, providing HOWTOs for writers, and preparing the project’s infrastructure to migrate from the old Publican 2-based publishing system to Publican 4 and Koji.

The FAD had two meeting locations, one at Red Hat’s office in Raleigh, NC, and the other one at Red Hat’s office in Brno, Czech Republic. We set up a teleconference call that also allowed remote people to participate.

Other docs team members have already blogged about the progress we made over the course of three days. There is still a lot do, and you are welcome to join the fun.

At the FAD, I also published a new revision of the Fedora Software Collections Guide, which serves as the official manual for people getting started with Software Collections (SCL) packaging. The guide can be useful not only for Fedora packagers, but also for people packaging for EPEL 5, 6, and 7. The SCL packaging guidelines are currently being approved by the FPC and Marcela drafted a proposal to include the first SCL (ruby193) in Fedora 21. Even though SCLs are not yet officially supported in Fedora, you can already get the ruby193 SCL from the Copr build system.

Thanks to all the FAD attendees, and to Red Hat for taking care of us throughout the event, for providing the meeting space and great catering!

For Czech speakers, I also put together a short report which you can read on fedora.cz.

GNOME Docs Hackfest 2014, Norwich, Day 2

Today is the second day of the GNOME Documentation Hackfest 2014. A group of community documentation writers is here in rainy Norwich, UK to work on getting GNOME’s help updated for the upcoming 3.12 release.

Today I am going through the bugs filed against the system-admin-guide in gnome-user-docs, and putting together a list of topics that are not yet updated or covered in that guide. Andre already updated or closed many of the bugs (thanks, mate!), so the bug pile for the guide now looks slightly better.

There is also some not-yet-upstreamed system administration material written for GNOME 3.8 and RHEL7 Beta that we published as a part of RHEL7 Beta product documentation. Since the 3.8 upstream release, there have not been many major changes in terms of what we want to have covered in the GNOME system admin guide, so I will be syncing our downstream docs with the upstream guide and updating the docs as needed. The goal is to release a reasonably complete system administration guide for GNOME 3.12, mostly following the outline detailed on the original planning page.

The hackfest wiki page highlights some of the other areas that we plan to work on this week.

I would like to thank Kat & Dave for organizing the hackfest and letting us stay at theirs for the week. Thank you so much! I would also like to thank the University of East Anglia for providing the venue, and the GNOME Foundation for sponsoring me to be here.

sponsored-badge-simple

GUADEC 2013 in Brno

Today was the last conference day of GUADEC 2013 and I have to say that being involved in the conference organization and volunteering has been an amazing experience. I want to thank my fellow organizers, our volunteers and all the people who offered their help to make GUADEC in Brno happen. You were great!

This year’s program included a number of talks related to community outreach and documentation. On Thursday, Kat and Sindhu talked about how to get involved in community efforts such as the GNOME Docs. At the Newcomers Workshop organized by Marina and others, I had a chance to meet our newest member of the Czech localization team. Our team, just like pretty much any other, needs fresh blood, so I was more that happy to see so many newcomers attending GUADEC, including those who are also interested in other aspects of the project than just coding.

At the GNOME Foundation AGM on Friday, Sindhu gave an update on GNOME documentation and I talked about what GNOME Localization has been up to since the last GUADEC in A Coruna.

Kat gave a talk on documentation on the third day. Later that day, we had a lightning talk session and I talked a bit about Getting Started video tutorials that we introduced in GNOME 3.8. Today, Marta gave a presentation on the developer tutorial for GTK+, followed by Jeff Fortin who gave a talk on PiTiVi and showed us some really funny videos.

It’s probably needless to say that conferences like GUADEC are special in that you can finally meet in person other members of the teams that you are involved in. Seeing familiar and new faces is always nice.

Next week

Next week we plan to have a docs hackfest, which will be focusing on the GNOME Desktop System Administration Guide. GNOME translators also plan to discuss some hot topics in GNOME i18n, such as broken translations for the gnome.org website, a l10n workflow for translating Git submodules, auto-committing translation files to GNOME Git repos etc. One of the outstanding issues we had appears to be already fixed – big kudos to Matthias for that.

If you are interested in GNOME docs or l10n, be sure to join us for the shared docs & l10n session we will have on the morning of the 6th. So, see you next week!

Brno Doc Sprint Update

If you are contributing to GNOME documentation, probably you already read about the Brno Doc Sprint (and the Developer Conference) that takes place in Brno, February 17-21, 2012, at the Faculty of Informatics at Masaryk University (from February 17-18) and at the Red Hat Czech Office (from February 19-21).

For those of you attending this documentation event, the organizers have special arrangements with one of the hotels near both doc sprint venues to provide the attendees a discounted rate. See the Developer Conference wiki page for more details.

To be able to receive the discounted rate, please confirm your attendance by January 9, 2012 on the doc sprint wiki page.

Please also remember to fill in your arrival and depart dates, and, since the special rate is for double-bed rooms, your roommate.

See you all in Brno!

The Developer Conference 2012 poster

Sylpheed FAQ revision 2.2 released

Sylpheed FAQ revision 2.2 released on 2010-08-09
================================================

New revision of Sylpheed FAQ has been officially released from the Sylpheed Documentation Project to reflect changes in the upcoming Sylpheed 3.1.

You can view the FAQ either as a multi-page or single-page HTML document at:

http://sylpheeddoc.sourceforge.net/en/doc_faq.html

Or download it together with source DocBook XML files in a .tar.gz or .zip archive from:

https://sourceforge.net/projects/sylpheeddoc/files/

The source DocBook XML files are also available in the Project CVS repository, see:

https://sourceforge.net/scm/?type=cvs&group_id=20952

Changes over the past 4 months
------------------------------

* New Q&A "Can I run multiple instances of Sylpheed?"
* New Q&A "Execute command for my dynamic signature seems not to be working!"
* Updated Q&A on environment variables
* Updated Q&A on automatic name completion
* Updated Q&A on Sylpheed plug-ins
* Other minor edits throughout the document
* To better comply with the GFDL license, the source DocBook XML files together with the plain text copy of the GFDL license and appropriate legal notice are now distributed in tarballs with each documentation release, and the exact way of how to obtain the source files is mentioned explicitly in the document; thanks to Ricardo Mones for pointing these legal issues out

All other information on the Sylpheed Documentation Project including how to contribute to the documentation effort is available at:

http://sylpheeddoc.sourceforge.net/

Contributors to this and previous releases
------------------------------------------

Paul Kater, Jens Oberender, Francois Barriere, Olivier Delhomme, Petr Kovar

Enjoy!

Documentation, GFDL, etc.

Last summer I found myself delving into documentation writing & maintaining. My email client of choice, Sylpheed, which many FLOSS users might remember from early 2000′s when it was one of the first full-featured GTK+ clients (at least as far as I know), was distributed with a set of long-time unmaintained documentation that quickly became more or less completely out-of-date.

In fact, it wasn’t touched for over three years and was left in a state of partially completed LinuxDoc SGML to DocBook 4 XML migration. The first thing that needed to be done, even before finishing the migration and previewing the actual documentation, was obviously evaluating whether it is actually worthwhile for a new maintainer without deep knowledge of the given maintenance rules & processes to try to continue with updating the original documents, or whether it would be better to start from the scratch, i.e. with a complete rewrite.

Since I wasn’t feeling very adventurous and my previous experiences were quite limited, to say the least, I eventually sticked with the former option.

Now I can say that the biggest obstacle is not a need to understand DocBook 4, neither it is adapting work flow procedures and writing style of documents with numerous authors in their history, it is actually dealing with the GNU Free Documentation License, the license the said documentation is distributed under. I believe that many rants have been written before already about this piece of legal text, so I won’t repeat others here. Still, I’m quite grateful for Creative Commons licenses as something fresh and needful coming into scene and replacing GFDL within many documentation teams & efforts. I wish it was more feasible for maintainers to relicense a documentation work done by many (inactive and probably unreachable) authors from GFDL to CC. That being said, the clause that appeared in the GFDL version 1.3 is/was apparently not very helpful, unless you wanted to relicense content on Wikipedia or something very similar.

Anyhow, what I have found in my experience (IANAL) to be least amusing about GFDL is:

  • The idea behind invariant sections etc. (Yes, I can understand those good intentions that went pretty wrong, I would say.)
  • The definition of a transparent format.
  • The need for distributing the full text of the license along with a licensed document.
  • The thing that a generated HTML file with included GFDL copy (i.e. a generated file converted from DocBook XML source files) is or at least might be seen as an opaque copy, that is one needs to distribute a (plain text) file with full text of the license along with HTML file distribution (be it via tarball or any other standard channel). This issue was brought to my attention by Ricardo Mones and discussed on the Sylpheed mailing list.

Planet Fedora

So after crying my eyes out, I realize that this is my first blog post that might land on Planet Fedora, so I would like to say hi to all the hopefully interested readers out there! You can find most of my Czech localization & documentation writing contributions upstream, however, with me joining the Fedora Czech translation team ca. two years ago, and enjoying my encounters with the Fedora l10n infrastructure, notably the Fedora Transifex instance, ever since. Though I do remember the times when translate.fedoraproject.org was running a Damned Lies fork, also. OK, not too far away history, anyway.