Open Help Docs Hackfest 2013

 

Open Help Conference 2013

Sponsored by GNOME FoundationAfter the first two “official” days of the Open Help Conference, GNOME Docs team “officially” started their second hackfest this year.

The plan was to revamp the Platform Overview with info from the recent DX hackfest and overhaul the developer.gnome.org. First day saw a lot of brainstorming, rearranging of post-its with existing and to-be-written topics, and engaging in some animated discussions about the appropriate type of support material for the new contributors.  

Shaun and Kat reworked the index and structure of the new platform overview, Michael wrote the stub pages about preparing the applications for translation, Gord updated the Get started tour, Tiffany finished the Vala examples for platform demos, and I wrote the stub pages about the procedure for adding user help to applications. Our resident programing wizards, Dave and Ryan, did the reviewing and answered a lot of questions. The results can be seen in master in the new-platform-overview directory.

 

Wireframing content for the new contributors

Wireframing content for the new contributors

Brainstorming the structure of the GNOME developer documentation

Brainstorming the structure of the GNOME developer documentation

Ryan also embarked on a new endeavor: motivating experienced GNOME developers to contribute to documentation by making the How Do I? style tutorials about the new technologies in GNOME. The idea seems to have taken roots and there are already various tutes written on the wiki, together with How do I write a HowDoI?

On the last day I took some time to contribute a couple of patches and revisit the user docs of Getting Things GNOME and Gtranslator apps (which were my last year’s GOPW projects) since they needed an update of the license information for all the Mallard pages. I should dedicate some time to a serious revision of GTG user docs, and follow closely this year’s GSOC project to redesign and port Gtranslator to Vala. The new app has the work-in-progress name ValaCAT and the code is on GitHub.

 

Team (and circulation) building

Team (and circulation) building

Bourbon tasting with Molly Wellmann

Bourbon tasting with Molly Wellmann

UK ales tasting (I still can’t believe Dave and Kat actually dragged those glass bottles all the way from England…!!!)

Far from being all-work-no-play, hackfest also meant we gathered daily with other teams that were doing sprints (Wikipedia, WordPress, FreeBSD…), enjoyed Cincinnati gastronomy and the intriguing experience of bourbon tasting with Molly Wellman, one of the best local bartenders. The atmosphere of Japp’s Since 1879 in Cincinnati’s historic Over the Rhine neighborhood was quite movie-like.

 The last evening Shaun took us to Mount Adams (gorgeous view of Cincinnati downtown, day and night), for the farewell dinner in a real pottery kiln!!! That was the first for me… :)

 

Open Help sponsors

Open Help sponsors

Thanks to Shaun McCance for organizing the conference and sprints (and yes, I was serious about doing it in Barcelona in the future!), and Mozilla, WordPress, GitHub and Red Hat for their sponsorship. My participation was possible thanks to the GNOME Foundation generous travel grant.

Family portrait in the Rookwood’s kiln

 

Open Help 2013

 

Open Help Conference 2013

Sponsored by GNOME FoundationBack in Cincinnati for my second Open Help Conference and Sprints, thanks to GNOME Foundation generous travel grant. Conference opened on Friday evening with a reception in the Italian bistro on Fountain Square in Downtown Cincinnati. Good food & wine and an open air concert on the busy square below us gave an interesting background to our geeky gathering.

Reception at Via Vite

Reception at Via Vite

Concert on the Fountain Square

Concert on the Fountain Square


    

Saturday sessions started with Jorge Castro, Cloud Community Liaison for Canonical, who talked about why and how their own StackOverflow site came to life at AskUbuntu, and what did it mean for then existing user support structure.

 

Software for discussion co-opted for user support.
Give people the proper tools and they make awesome stuff.
Powershift away from mods to the community.
SaaS isn’t for everyone.

 

Michael Verdi, Content Manager of Mozilla support presented SUMO, Kitsune, Squeaky and the Army of Awesome.

 

“If you want them to RTFM, make a better FM.” – quoting Kathy Sierra

Make add-ons awesome

https://wiki.mozilla.org/AMO/Squeaky

 

During the afternoon panel discussion we heard Jorge, Michael, Jeremy Garcia of LinuxQuestions.org, and Siko Bouterse from Wikipedia, while Rich Bowen, OpenStack Community Liaison at Red Hat, talked about listening to the audience.

 

“A major part of documentation is to help people not feel stupid.”

 

Sunday sessions included:

 

Doc sprints: The ultimate in collaborative document development from Sarah Maddox

 

 

If you couldn’t make it to this year’s Open Help, you can still get a pretty good picture from the awesome notes Siobhan McKeown from WordPress took during the conference. Unfortunately, no notes can make up for all the insightful conversations and fun while commingling with other open-help-folk… ;)

 

Wrapping up – Integrating Mallard Help into GTG

 

(this post was originally published on GTG Blog, on July 23, 2012)
 

If you already installed the 0.2.9.r1206 release, than you can meet our newest “baby”: brand new GTG user docs in Mallard!

GTG

Delivery of this baby was pretty painless (no need for an epidural ;) :

- Bertrand and Izidor received the Mallard files that I prepared

- after some brainstorming they decided to follow the standard procedure (check this resource on Stackoverflow):

  • Mallard pages are placed in the doc/userdoc/C folder (once we have the user docs localized, each locale will go into its own subfolder (es_ES, sk_SK, it_IT…)
  • setup.py file has been modified to install those pages in the $PREFIX/share/help/$LANG/gtg folder
  • Contents item has been added to the Help menu and the browser code has been modified to open help:gtg when pressing F1
  • Help button has been added to the Edit > Synchronization Services dialog to open directly the respective help page

Of course, as Murphy’s Law demands, as soon as the release was ready and public, I noticed a couple things that needed revision and correction. Documentation is a work-in-progress – it will need periodic revisions and improvements!

The next step is including the GTG user docs into the GNOME Library. However, since it is not part of the official modulesets on git.gnome.org, we’ll have to file a bug at Bugzilla for the component library.gnome.org. That way, the userdocs that are now included into the GTG tarball will be processed by library-web autotools build system and become available online as the rest of GNOME user apps.

Mallard Docs on the Web

 
(this post was originally published on GTG Blog, on June 25, 2012)
 

Countdown for the version 0.1 of the GTG User Docs in Mallard format is on… :)

I am collecting the last suggestions and corrections from the developers and in about one week or so, on behalf of all of us from the GTG team, I hope to present to the world the final result of the GTG User Documentation in Mallard effort. Izidor has been triaging the bugs for the 0.3 version and hopefully the docs will be integrated into the app by then.

During the last week I have mostly been experimenting with the yelp-tools. Handy one for checking the validity of the Mallard pages is this:

yelp-check validate *.page

For example, if you forget to close a tag, Yelp will not even open the .page file! This leaves you a bit frustrated since you do not know where to start looking, especially if the page is long. Solution is to run the ‘yelp-check validate’ command and you will receive the info about the error:

yelp-check validate gtg-translate.page
gtg-translate.page:19: parser error : Opening and ending tag mismatch: app line 19

The above example was a clear indication that I left out the closing </app> tag on line 19 of the gtg-translate.page file. Problem solved! :)

Next yelp tool to use was the:

yelp-build html *.page

When run in the folder with all your .page files it will output the HTML files from Mallard. Here you can browse the HTML version of the GTG User Documentation. Once the docs are ready, we will publish them on the new GTG blog (yes, we are working on that too ;) and they will also be included into the GNOME Library.

All the above commands assume that you have installed yelp-tools on your system. Check these posts by Tifanny and Shaun for more details.

Linux Screencasting, Video Editing and Venus Transit

 
(this post was originally published on GTG Blog, on June 7, 2012)
 

Writing the user docs for GTG was coming along quite nicely but I wanted to add a little kick so instead of all screnshots, I decided to make some screencasts. This was a completely new task for me as I never did any screen recording or video editing on Linux. But hey, this GNOME experience is about doing the things the new way, right? ;)

As far as recording what happens on the screen, the choice seemed clear – recordMyDesktop. This a is simple, no frills app, works consistently and produces a decent result. I did not, however, test any advanced options so those remain to see…

OGV video file that recordMyDesktop outputs works perfectly in Mallard with a simple syntax:

<media type="video" src="videos/get-started.ogv"/>

The intention was to keep the video file size as small as possible so I did not record the audio. Unfortunately you can not do much more with recordMyDesktop apart from, well, recording your desktop. The problem with the straight recording is that it does not offer enough visual clues as to what are you doing especially if you do not provide audio. However, I was unable to find the program equivalent to Camtasia for Linux – something that is easy to use but offers certain features for making instructional videos. PiTiVi seemed too simple and has only one video and one audio layer* and I found both Kdenlive and LiVES not very intuitive and way too complex for what I had to achieve. There are more video editing apps available (Cinelerra, Blender…) but again, it would be like using a cannon to kill a mosquito.

So at first it seemed that I had no other choice but to jump back to Windows, edit the screencast to add some color and callouts with text, and reimport the video into Mallard page. This approach involved the additional requirement of converting the OGV file. I found that both OggConvert and Transmaggedon did a very good job. You can see the result by clicking on the image below:

GTG

Video lost a lot of quality during the YouTube conversion but the version that will be in Mallard is decent enough. The ideal situation would be having a video editor with at least basic instructional features that can handle the OGV files natively so there is no need for conversion that is almost always lossy.

After accomplishing this step, I remembered that the user documentation files will eventually be localized so the embedded text is not a solution. I also remembered that Tiffany mentioned that videos in Mallard can be subtitled easily and that’s the work I have ahead. Stay tooned… :)

PS: Venus revealed itself for the last time this century right on my birthday! Here is how NASA saw it (click the image to open the video in a new window).

* Thanks bronte for commenting that this is indeed possible… :)

GTG User Documentation Project – Call for FAQs

 
(this post was originally published on GTG Blog, on May 29, 2012)
 
 


image ©2008-2012 ~VanHeist

Hi everybody!

My name is Radina and I just started my GOPW internship during which I will be writing the User Documentation for Getting Things GNOME!

Yeah, I know what are you thinking: It was about time! Izidor had already put some basic stuff on our wiki some time ago, but baring some natural disaster, by the end of this summer GTG will have a proper topic-based user manual written in Mallard language – the standard for GNOME apps.

In case anybody is interested to see the overall structure and the draft of the first guide and topic pages – just check the project on Gitorious repository.

The idea is to include the comprehensive Frequently Asked Questions topic into the User Documentation, and for that I was thinking of asking all the Getting Things GNOME! users and collaborators for help.


image © electricjonny

You may try to remember all the questions you asked yourself about the GTG usage on one point or the other, since you first installed it; and all the “How the hell do I…?” and “Eureka!!!” moments… :)


image © uizu

If you are willing to lend us a hand with compiling the list of useful questions, you can post your suggestions here or, if you have an account for GNOME Live!, just edit the GTG FAQ page that Bertrand started recently.

Before the end of my internship I will revise all the questions and include them into the final version of the GTG User Documentation prior to its release.

Thanks in advance for all the help!


image © ipyuri

What the heck is a “Hackfest”?

   

Open Help Conference Sponsors

This year I attended the Open Help Conference for the first time. Due to some prior engagements, I arrived to Cincinnati (well, actually, Newport, KY) on Sunday, second  day of the conference, and bumped into the whole group right on their way to find a place to taste the famous local chili.  This was the first time I was actually meeting anybody from the GNOME Documentation Team in spite  working together online for almost 3 months during my GOPW internship. After the initial presentations I was swiftly released from carrying my bag, and on our way to the restaurant and back, Jim, Mike, and even Florian Nadge and Anne Gentle, were taking turns in carrying it for me. “Now this must be one curious group…” I thought, “Where did you hear that the conference speakers carry the traveling bags of lowly interns?” 

Unfortunately, I missed some very interesting talks for arriving so late. I would have loved to hear Janet Swisher’s presentation of Kuma and Popcorn Maker, Florian’s talk about Publican, and  Warren Block’s one about Automating Documentation Proofreading with igor (PDF). Shaun, if by any chance you are reading this, let me know how can I get my hands on those videos you recorded? ;)


Family portrait

 

Team brainstorming

Being  new to the GNOME universe, it was also the first time I participated in a hackfest or a sprint. Fortunately Wikipedia did have an entry for it, otherwise I would have imagined anything from front running with the laptop on my back, to some wild geek party. Life is not easy when you are a hacking newbie, but it gets so much better (and more productive) during this thing called the hackfest. Granted, IRC and mailing lists are very good means of communication when you are a member of some distributed group, but being in the same room with the whole team is priceless. It has been a great treat having Tiffany right beside me to help figure out some misbehaving Mallard tags, or Jeremy to straighten out other misbehaving upgrade packages.  I was determined to round off the first version of the Gtranslator user documentation before the end of the sprint, but that was quite a challenge sometimes, having Shaun and Ryan just across my desk, discussing the intricacies of Vala, or the docs team and GNOME strategies. Trying to understand some of their conversations and “mallardizing” at the same time was a rewarding, but not an easy task. On the other hand, however complex their subject had seemed, they were always more than willing to “dumb it down a notch”, explain anything and answer all the questions.

Hacking the midnight oil

Our fearless leader making a crucial decision for a team project

Last penny for knowledge

Jim and Mike were a pleasure to work with, and Taryn added another human dimension to our gathering. Fostering diversity can be a daunting task sometimes, but it is well worth the effort. Having been present for this team’s discussions, and witnessed the work they put to reconcile the arising issues and differences of opinion (and in such a way that everybody can feel included), this lowly intern is proud of her new community.

Even though we were hacking the midnight oil every night, we still managed to have heaps of fun, taste some local Cinci & Newport treats, and even muse about religion (or lack thereof) in the small hours of the night (it wasn’t me who started it, scout’s honor!).

Team enjoying the Newport skyline

GNOME lost in the Reds Ballpark?

Docs team never rests, not even in the line for Graeters


Thanks to Shaun McCance for organizing and hosting this event, to Mozilla, Red Hat and W3C for sponsoring it, and to GNOME Foundation for providing me with the travel grant. I have learned a lot, tried to contribute as much as possible, and got inspired to continue doing so in the future.

 


The first of my GNOME summers…

 

…is almost over! The old “time flies when you are having fun” cliché has, yet again, been proven right.

Still, I don’t feel like saying goodbye to anything. Not only because I’m positive that tomorrow I’ll still be fighting with git commands, Mallard tags, do-I-write-this-as-a-separate-topic doubts; or reading the conversations on #docs channel and posts on Planet GNOME instead of getting things done; or bugging Tiffany with questions; or thinking for the umpteenth time why the heck didn’t I learn to code years ago…?

Thanks to the Women Outreach Program, immersing myself into this GNOME and open software waters has not only made my summer 2012 one of the most refreshing and exciting ever, it has also served as a kind of baptism (if such an expression is allowed to a fundamentalist skeptic like myself) into a new community of which I fervently hope to continue being a member for a very, very long time.

 Getting Things GNOME! Documentation

My first baby is almost two months old now, and will officially be presented to the world in a few weeks, when the 0.3 version of GTG is released (lucky ones with the gtg-daily-ppa, have already had the pleasure of being acquainted).

I approached the task of planning and documenting GTG features with enthusiasm and armed with my experience in writing user documentation for Windows based closed source applications.  Along the way I had to learn the basics of git commands, understand the logic behind the Mallard tags, get to know better the structure of Linux OS, figure out the way to effectively screencast, edit and render videos with open source tools, put myself in the shoes of the heavy GTG user…

GTG developer team has been a pleasure to work with: Bertrand (my co-mentor), Lionel, Izidor, and many more reviewed the draft versions of the docs promptly and patiently, and their input has been essential for the quality of the final result.

Even though docs are finished – for now, at least ;) – I remain involved in the project as a community manager and at the moment I am working on the new GTG website (still work-in-progress, be sure to visit in a couple of weeks). All in all, I am very proud to be the part of the Story of Getting Things GNOME!

 

 

Gtranslator Documentation

Being a member of the GNOME Spanish Translation team made the choice of my second OPW task easier, as Gtranslator was in dire need of revised userdocs. Rewriting an existing documentation is a slightly different challenge, but I could always count on (if not the whole development team), the essential help of Daniel Mustieles,  Spanish team Coordinator.

Since I was finishing my Technical Communication Certification at the same time, I decided to approach the writing of the new Gtranslator docs in a more structured manner, starting with the draft proposal and the proper Information Plan. Time was also well spent on information model analysis, prototyping topics and diagramming the navigation. I also realized that I’ve barely scratched the Mallard linking and section features, and now I can’t wait for the adequate documentation task to try them on. Considering that I plan to dive into DITA very soon, I am hoping that these months of “thinking Mallard” will help me get into that rich-semantic-markup mindframe more easily. Check out the final version of the user docs in HTML format, Mallard pages on git.gnome.org, Gtranslator Help Information Plan  (PDF file), and the slideshow presentation (ODP file).

 The best part of the Gtranslator user documentation rewriting was that I have crossed the finish line during the Docs Team Hackfest after the Open Help Conference. I’ll write about that experience in a separate topic, erm…, post (“thinking Mallard” runs deep, as you can see), but I can’t end this story without mentioning how awesome that group is, and how much I enjoyed working side-by-side with each and every one of them. Even though I haven’t been able to attend GUADEC in July this year, meeting all of you in person during the doc sprints made up for it!

 

Last but not least, I want to thank Google, Mozilla, Collabora, the Free Software Foundation, and Red Hat, for their generous sponsorship that made the GNOME Outreach Program for Women possible for all of us interns.

Special mentions go to my mentor Tiffany Antopolski (for always being there, yet still letting me be), to GOPW organizer Marina Zhurakhinskaya (see you at the next ADACamp!), and to Karen Sandler and the rest of the GNOME Foundation Board of Directors. You ladies (and gentlemen) rock, and I hope that one day I can say that I’ve contributed to FOS cause even just a fraction of what you did!!!

 

And now I’m off to my first GNOME autumn… See you there!

 

 

Gtranslator Help – Visual Design and Navigation

Gtranslator Online Help Information Plan (continued)

Visual Design

Visual and style decisions regarding the user documentation that opens from the Gtranslator program are mostly constrained by Mallard document structure and formatting and the way it presents inside the GNOME Help Viewer called Yelp.

Yelp window

Yelp window

Yelp window by default opens with dimensions of 600×420 pixels, but it can be resized, and it remembers the size previously set by the user.

Mallard pages  can display the majority of the common block  (paragraphs, lists, tables, figures…), information (metadata and automatic links for pages and sections), and inline elements , but according to its Design Principles , Mallard tries to avoid the DITA-like  rich semantic markup with the intention of making the process of writing documentation easier. However, projects that need more specific markup can always use style hints or markup from external namespaces.

Once the standard HTML files are built from the Mallard pages for the online version of the help files, the relative CSS file can be edited to achieve specific formatting.

Even though there is a specific GNOME Documentation Style Guide, it has not been updated since June 2005, and most importantly, it is outdated regarding the transition of GNOME user documentation from DocBook to Mallard format. For this reason, the decision has been made to follow only the general guidelines for writing the technical documentation as stated in the style guide, and to be ready to revise the Gtranslator online help regarding the more specific Mallard documentation aspects, once the revised GNOME Documentation Style Guide is released.

Navigation Plan

The window of the GNOME help viewer called Yelp contains the Previous and Next buttons, and the Search box below the main menu. User can go back to the previously visited topic, or search by keyword at any time.

Gtranslator user can open the help file from the application’s menu or with the F1 key. Context sensitive opening is not present by default and will have to be programmed separately.  

Yelp start page

Start page serves as the Table of Content and the user can always go back to it by using the breadcrumb links at the top of each topic page. Topics on the start page are grouped in sections and sections headings are displayed in the breadcrumb links as user navigates through the topics.  Each topic page has the More About and See Also links at the bottom of the page that connect the topic in question with other from the same section.
Paragraph inline links can open another topic page or an external web page.   

Navigation in Mallard

 

Gtranslator Help – Topic Prototypes

Gtranslator Online Help Information Plan (continued)

Next step in writing the Information Plan for user documentation and online help is to decide the elements that need to be included into each topic type.

Information ModelTypes of topics for the Gtranslator help

  • concept
  • task
  • reference
  • FAQ

List of Elements for each Topic Type

* optional element

Concept

Topic: Understand Translation Memory (TM) concept

  • Title/Heading
  • Context/Short description
  • Concept definition
    • Example*
    • Screenshot*
  • Note*
  • See also

 

Task

Topic: Perform the initial profile configuration

  • Title/Heading
  • Context/Short description
  • Steps
    • <step1> + screenshot*
    • <step2> + screenshot*
    • <step3> + screenshot*
  • Result*
  • Note*
  • See also

 

Reference

Topic: Gtranslator Plugins

  • Title/Heading
  • Context/Short description
  • Item 1
    • screenshot 1*
  • Item 2
    • screenshot 2*
  • Note*
  • See also

 

FAQ

Topic: Gtranslator FAQs

  • Title/Heading
  • Context/Short description
  • Question 1
    • Answer 1
  • Question 2
    • Answer 2
  • Note*
  • See also