j1m.net

West Coast Docs Hackfest - 2019

Mon, 24 Jun 2019 12:24:42 +0000
This past week I joined several other members of the GNOME docs team (as well as the Engagement and GTK teams) to work as part of the West Coast Hackfest</a> in Portland, Oregon. From the GNOME Docs side, our efforts were split between resolving documentation issue reports, improving our CI, and making some initial steps towards better help on the web.
On the issues side, we resolved over 20 doc issues, many of which involved multiple components and discussions to arrive at the best way to fix the problem. For myself, I revamped the instructions on how to search from within the GNOME Files / Nautilus application, which mainly involved updating the current help and adding information on how you can customize which directories are included (or not included) in the search results. As part of this, I also filed a bug</a> to improve a UI component of the search customization. I was able to give a bit of love to gedit docs, as well, though there is still more to do to bring those docs fully up-to-date.
For CI, Dave King integrated some yelp-check</code> validation tests into our CI process. Because these tests run quickly, we moved them close to the start of the CI process so that the tests will fail early-on if there are syntax issues in the documentation.
A good chunk of our efforts on the latter days were spent on an update tohelp.gnome.org</a>, which we're initially targeting for the 3.36 release. The update involves a transition from 'Library Web' to 'Pintail</a>' as our site building tool. This will allow for easier site maintenance by a broader group of contributors, which will make everyone in the whole world very happy. There's a good chunk of back-end tooling that needs to be in place before we stand anything up, so we don't have any user-facing drafts for people to see, but it was well-worth our time to start on this with so many of us in the room.
Although we'd like to do more with transitioning from Mallard XML to Ducktype, our primary focus over the next releases is going to be on making sure documentation stays up-to-date and that we improve the web help situation. Getting the latter component in place is critical to making our documentation easier to maintain in the future.
As a side note, I'm fortunate that my employer</a> fully funded my attendance at the hackfest, and is supportive of my contributions to GNOME.


About
Sun, 19 Nov 2017 00:00:00 +0000
</p>
My name is Jim Campbell. I am a contributor to the GNOME Documentation
Project</a>, and am a co-organizer of
the Chicago GNU/Linux User Group</a>. I currently live in
Chicago, Illinois.</p>
If you'd like to get in touch with me, feel free to send me an email! You can
reach me at: jcampbell - at - gnome dot org.</p>
Site</h3>
This site is built with Zola</a>, a Rust-based static
site generator.</p>
License</h3>
All media and text on this website are provided under the CC-by-SA
4.0</a> license unless otherwise
noted.</p>


LibrePlanet 2016 - Freedom Sympatico
Fri, 25 Mar 2016 00:24:42 +0000
Hello!! I emerge from my blogging slumber as part of some post-hospital-merger
/ post-Affordable-Care-Act-administration free software activities. You see, I
went to LibrePlanet this past weekend, and I was as happy as this guy to be
there:</p>
</p>
The various LibrePlanet session videos are making their way out to the
LibrePlanet MediaGoblin instance</a>, and I
encourage you to check them out as they become available. It was a well-run,
informationally-dense conference.</p>
This year's event seemed to have a bit of an advocacy and social justice bent.
I'm thinking in particular of LittleSis</a> and of the
Library Freedom Project</a>. I'm also
thinking of Luis Villa's talk, where he drove home how we can't just give
people software licensed under the GPL and think that they automatically have
their computing freedom - that we need to make that software compelling for
users to actually want to use. I found this to be sympatico with some of the
recent work and discussions around UserOps</em>.</p>
On the technical project side of things, Ring</a> seems
interesting, though in early stages of development. GNU
Guix</a> seems to at least be beta quality.
GNOME is now available as a desktop in GNU Guix, so I may be checking it out
soon.</p>
DRM and the W3C</strong></p>
Something that wasn't part of the conference, but which immediately followed
it, was a rally against inclusion of the Encrypted Media Extensions
specification. The spec is currently under consideration by the W3C. If you
want more info about the protest, Chris Webber gave a thorough
recap</a> of it,
along with details of the post-protest roundtable discussion at the MIT Media
Lab.</p>
The interesting thing about the EME spec is that it doesn't describe DRM - it
just seems to describe an intricately shaped hole in which the only thing that
will fit is DRM.</p>


Reflecting on Feedback
Mon, 23 Feb 2015 22:34:42 +0000
</p>
While at last month's Cambridge Hackfest, members of the GNOME Documentation
Project team talked with Cosimo Cecchi</a> of
Endless Mobile</a> about the user help in their product.
As it turns out, they are shipping a modified version of
Yelp</a>, the GNOME help browser, along with
modified versions</a> of our own
Mallard-based user help.</p>
Knowing that they were actually shipping our help, we wanted to get a closer
look at what they were doing, and wanted to get some feedback as to how things
were working for them.</p>

In terms of modifying the appearance of our help, their technical writers
found it difficult to modify the CSS that we use. Cosimo noted that the CSS for
our help is not stored in a single file, nor even a single directory -it's
partly embedded in Yelp's XSLT.</li>
</ul>
While not always ideal, there are reasons for this. For example, if a
person's visual impairment requires that they use GNOME's High Contrast</em> GTK
theme, Yelp will pick up the theme change and will use a corresponding color
scheme when it renders the help for that user. Similarly, if a user sets their
default system language to a Right-to-Left-based language (such as Arabic),
Yelp will also pick up that change, and will display the help in the
appropriate Right-to-Left manner automatically.</p>
These are both useful features, but it is good to get feedback on this.
Creating a custom documentation "look" is important for a downstream
distributor, so there's room for us to improve here.</p>

The technical writing team at Endless Mobile</em> customized the HTML output
to feature broadly-grouped sections as html-buttons along the left-hand side of
the help. I wish I had gotten a screenshot of this, because we were impressed
with how they grouped and formatted the help. This may be an approach that we
look to use in the future.</li>
</ul>
I talked with Cosimo about incorporating some of their updates into our help,
and he was very receptive to it. While we'll mostly be focusing on
content-related updates for our 3.16 release, we'll consider how we can improve
our help based on their feedback in the future.</p>


GNOME Docs in Cambridge: Day One
Mon, 26 Jan 2015 10:02:42 +0000
The Winter 2015 edition of GNOME docs hackfests is underway in Cambridge, UK,
and the first day is in the books. We're making some good, initial progress.
Thus far we've been able to update the status of Application Help on our wiki,
triaged a lot of bug and docs-feedback reports, and have made some initial
updates to platform developer documentation.</p>
</p>
Application Help Status Review</strong></p>
One of the first things we've looked at is the status of application help.
Ekaterina Gerasimova and I discussed and reviewed GNOME Application
Help</a>,
reviewing the status of each application, and setting documentation priorities
for the upcoming release and for future releases. We want to make sure that our
core set of applications is consistently covered for each release, and setting
the right priorities will help us in this effort.</p>
Feedback and Bug Review, Plus Various Fixes</strong></p>
Jana Švárová responded to comments that we receive on the documentation
feedback</a> mailing list.
The mailing list is actually the receiving end of mail that users send via the
GNOME help</a> website. If users spot a problem in our
help, they're able to click on a link at the bottom of the page, and let us
know of the issue they're experiencing via a simple email.</p>
With regards to bugs, Petr Kovar did a great job of [triaging
bugs](https://bugzilla.gnome.org/buglist.cgi?product=gnome-user-docs&resolution=
---) yesterday, triaging over 50 bugs in one day! This raises his status from
that of a bug triager</em> to that of a one-person Bug Medi-vac Unit</em>. Good job,
Petr!</p>
GNOME Developer Documentation Updates</strong></p>
Bastian Ilsø's main focus</a> for
the hackfest is update of the GNOME Platform demos. This includes GTK code
examples and small tutorials that help developers get oriented to GTK and GNOME
development tools. Because he's coming into this from the perspective of a new
GTK developer himself, he's able to identify areas that need to be fleshted-out
and made more clear for others who may be knew to the platform, as well. He and
David King are working through this quite a bit as we begin day two.</p>
Hosting and Sponsorship Thanks</strong></p>
All of this is possible because we have a good venue and have been able to
travel here to work together. Many thanks to
Collabora</a> for providing the working space for
this event.</p>
And, of course, additional thanks go out to the GNOME
Foundation</a> for sponsoring my travel to this
hackfest. We are off to a steady, and productive start, and are making good use
of our time here.</p>


Beyond Clicking: Refactored User Help for Passwords and Keys
Sat, 22 Nov 2014 16:54:42 +0000
Documentation doesn't just explain what buttons to click or what keys to press.
In some cases it provides reference information, or it explains a particular
concept that underpins a certain task or series of tasks.</p>
Explaining concepts is particularly important when those concepts are both
complicated and important to performing a task. This is the case with concepts
related to encryption. If people can understand complicated encryption
concepts, they may be more likely to correctly use and maintain their
encryption tools, making it more likely that they will keep their communication
secure.</p>
Updates to the Passwords and Keys Help</h2>
To make encryption concepts a bit more accessible (and thus help people
correctly use encryption tools), I've re-factored the user help for the
Passwords and Keys</a> application.
Passwords and Keys</em> is the application that manages SSH and PGP/GPG keys in
GNOME, and the updated help will be available in the GNOME 3.16 release.</p>
The updated help follows the layout of user help in other GNOME applications,
making it easier to scan the help and find relevant topics. I've also added a
few new topics:</p>
</p>
Some highlights include:</p>


A new, introductory section that groups together fundamental encryption
terms and concepts.</li>
A new topic that explains the difference between Public and Private keys.</li>
Suggestions for securely backing-up your keys.</li>
Instructions on how and when to revoke your keys.</li>
Showing how to sign someone else's PGP/GPG key.</li>
</ul>
</blockquote>
There's more to it, but that is a short list of some of the topics that stand
out to me as useful. I think it's good that we'll have that help included
on-disk (and also on the web</a>)
for anyone who needs it.</p>
Credit Where Credit is Due</h2>
As for the content of this help, I give credit to Aruna
Sankaranarayanan</a> who wrote
much of the user help for Passwords and Keys. I had written some if it, but she
wrote a lot of it - it's thorough and well-written. Although I have added a few
new topics, most of what I've done is to refactor the layout of the help to
make it easier to search and navigate.</p>
We'll likely have a some more updates before the 3.16 release, but if you have
any tips or suggestions for how we can improve the help, feel free to be in
touch.</p>


I'm on California Time
Wed, 01 Oct 2014 06:44:42 +0000
I've recently had some time to work on docs for
California</a>, a new calendar
application being developed by the Yorba</a> team.</p>
</p>
They've just released version 0.2 of California, so I thought I'd jot down a
few notes about the the application and the docs.</p>
California, the Calendar</h2>
This is only California's third development release, but it already takes care
of the modern-day calendaring basics (for example, syncing with CalDAV and
Google calendars). To me, though, the best feature of California is how it
allows you to enter event details using everyday phrasing.</p>
You can type out your events like this:</p>

Go to Economics class every Wednesday from 6:00pm to 9:00pm</em></li>
Meet James and Aaron for Dinner at 7:00pm @ Ombra</em></li>
</ul>
. . . and California will take care of adding the event(s) to your calendar.</p>
The parsers are already reasonably complex, and they keep making them better.
There are some event entry tips on the
wiki</a>, and I'll be
adding more of this information to the help as a separate, detailed topic.</p>
California, the Docs</h2>
As for the docs, here are a couple of notes:</p>

I noticed that Shaun McCance included some
Schematron</a> checks in the GNOME User Docs, so I'm
including those same checks in the California docs. I'm only checking for
proper use of <desc></em> tags and inclusion of a license file, but I can
set up more checks in the future.</li>
I'm using the Mallard
Expanders</a> feature so that the
user can choose help that is relevant to them and skip irrelevant information.
I like how this approach makes the help easier to digest for readers,
particularly for longer topics. Technical writer Tom Johnson talks about some
of the pluses and minuses of using this feature towards the end of a [recent
blog
post](http://idratherbewriting.com/2014/09/22/using-collapsible-sections-to-brin
g-tasks-and-concepts-together-dita/), too.</li>
There are a few areas where task instructions are similar across topics, so
I'm using xincludes and
xpointer</a> to
limit repetition of some common steps. This means a bit less work for
translators, and less effort for us to maintain the docs in the future.</li>
Although it's not a big deal in the gradiose scheme of things, I'm now
making an effort to follow the GNOME git commit
guidelines</a>. It's not difficult to
follow them, and it makes all of our work a bit easier in the long run. I hope
you'll review the guidelines and follow them, too.</li>
</ul>
There's still more to do with these help docs. I'll be adding more help topics
as development progresses, but things are off to a good start.</p>


GNOME CAKE 3.10 - Fully Baked, No Bugs
Tue, 15 Oct 2013 20:02:42 +0000
We had our October meeting of the ChicagoLUG this past Saturday, marking one
full year of meeting together at least once a month. Go us! We celebrated the
release of GNOME 3.10, had a talk, and had a good discussion about future plans
for the LUG.</p>
First, the cake. It was a special cake (Thanks, Meg!). Yeah, it was GNOME CAKE.
GNOME CAKE 3.10, actually. For anyone who wants to create such a cake in the
future, please note that using all caps actually makes it taste better.</p>
</p>
As we talked about the cake, some newer folks actually thought that GNOME had
create a Cake PHP application</a>. We cleared that up. And
then we ate cake.</p>
Freddy Martinez followed-up with a talk about encryption, giving us a good
amount of detail on various ciphers, and configuring your mail application to
send GPG-encrypted messages.</p>
Most of our time was spent discussion future plans for the LUG, though. Due to
a space conflict, we moved our meeting to the outdoor seating area of a pub
down the street (nice!). The big news is that
Rackspace</a> has granted us some generous cloud
server resources, and it's going to open up a lot of opportunity for LUG
members to experiment with server hardware, develop some new skills and build
some cool stuff.</p>


Flourish Conference
Sun, 14 Apr 2013 22:49:42 +0000
This past weekend I was able to attend and speak at the Flourish open source
conference</a> hosted by the University of Illinois
at Chicago. I say the event is hosted by UIC, but it's actually a student-run
event. The organizers had to do a lot more leg-work than usual this year, but
pulled it off well. Big, big kudos to the Flourish staff for yet another great
event.</p>
For those who would like to get a glimpse of what I talked about, my slides
are available for
download</a>. As you
may notice, I had a lot of fun with GNOME’s depiction of cats, particularly
when creating the slide that references how the GNOME team has iterated on the
initial GNOME 3.0 design:</p>
</p>
I think GNOME 3.8 is a great release, and the gist of the talk was that, if you
didn't like GNOME 3.0 (perhaps too many rough edges and stray cats), that GNOME
3.8 might make you want to take another look.</p>
I wasn't in the audience, so I can't say for sure, but I perhaps reached my
intended goal with at least one
person</a> in
attendance.</p>


GNUS of GNOME in Chicago, March Edition
Mon, 25 Mar 2013 22:50:42 +0000
This past Saturday we held our monthly ChicagoLUG</a> /
GNOME hackfest event at Pumping Station: One. It turned out to be pretty
informative and productive. Evil Joel Luellwitz gave a solid talk on Linux
security, explaining quite a bit about how /etc/passwd and /etc/shadow work. He
included details about various hashes and logic / programming decisions that
are incorporated into these core utilities to help keep the elite
hackers</a> out of our computers.</p>
</p>
He also explained a bit about choosing good passwords, highlighting how easy it
is to crack simple passwords. I think most of us know how easily simple
passwords can be broken. To think about how easy it is is still kind of
humbling, though.</p>
We had some new faces at the event, including one young woman who is just a
freshman in high school, and who made the trip up from the far south side of
Chicago. She had heard about Linux, and a page on Linux.com encouraged her to
find a local user group. She made the trip up to our event by herself, and Joel
even had to talk to her mom on the phone to explain a bit about the group and
reassure her that we are legit.</p>
Joel took the time during our hackfest portion to get a $DISTRO set up on her
computer. She seemed to pick up on things pretty quickly, and she’s going to
be giving Linux a shot! Not even dual booting – just going cold turkey. We
all wished that we’d had the intuition and nerve to seek out such groups at
her age.</p>
The hackfest portion went well. Meg worked on adding CSS classes to UI elements
of a GJS application that she’s been working on. Adding those classes will
allow her to apply theming elements to the UI using regular CSS, and by the end
of the day she was able to display her app with both light and dark GTK themes.
Good stuff.</p>
Andrew Spalding got to working on the new GJS-based GNOME-Music application,
and I think he was able to get it to build by the end of the session. I
reviewed about 20 of Sindhu’s gedit documentation patches, and merged them
into master by the close of the day. Sindhu has been doing some solid work, and
has moved on to the Rhythmbox documentation.</p>
Most people headed home at around 5pm, but a few of us stuck around a while
longer, and got sucked into unloading an electron microscope that had been
donated to the hackerspace. Pretty sweet! Also pretty heavy.</p>
We won’t be having a hackfest in April, as we have both Flourish and
Penguicon coming up next month. We hope to set up a booth at Flourish, though.
And I’m going try and get some ChicagoLUG stickers for the event.</p>
Many thanks to the GNOME Foundation for sponsoring food for this hackfest. : )</p>
See you around. : )</p>


GNOME Docs Hackfest - Day One - Complete
Sat, 23 Feb 2013 15:42:42 +0000
It was a long day of travel to get to the GNOME docs hackfest in Brno, but I
arrived safely on Friday. Knowing that they would be concerned, I sent my
family a picture to let them know that I was ok, and that I had indeed made it
to the Czech Republic.</p>
</p>
This picture was taken in Prague, where we met up with Andre Klapper for lunch.
Andre and Florian Nadge gave us a brief tour of Prague on foot, but we still
had an almost three hour bus ride to Brno. It was a long day.</p>
After a restful night of sleep, we woke up, got started, and day one of our
hackfest is now in the books. Overall it was a very productive day, and I feel
like we're off to a very good start.</p>
We started at about 9:30am, laying out goals and plans for the hackfest. Here
are some of the goals that we laid out:</p>

Revised GNOME help for version 3.8</li>
gedit updates that reflect the switch to gmenu (almost complete now)</li>
Merge updated gedit snippets for Mallard. The new snippets incorporate the
syntax of the entire Mallard 1.0 draft specification (many thanks to Jaromír
Hradílek for his work on this)</li>
Assist Sindhu with gnome-terminal documentation</li>
Passwords and Keys documentation</li>
Updates to the GNOME Help landing page. These updates will be necessary to
have a smooth transition between the Getting Started videos and the docs.</li>
</ul>
We also discussed one process improvement. We're going to stop using
gitorious.org for draft documentation and just start using branches in the
appropriate projects on git.gnome.org instead. Using a branch on git.gnome.org
will simplify things for new contributors who ask what there is to work on (the
new contributor would only need to learn how to use git.gnome.org, and not also
learn gitorious), it will simplify the merging process once docs are ready for
merging, and it will also help teach new contributors about managing and
merging branches with git.</p>
It should make for a productive event!</p>


Chicagoans and GNOME, Part 3
Fri, 28 Dec 2012 06:12:42 +0000
Here is my first-hand report of our third consecutive monthly GNOME hackfest,
held on Saturday, the 15th. We had our regular User Group meeting where I
presented some of the inner workings of our Flask-based website, and made a
note to follow-up with speakers who said that they would speak at events (it is
polite to either show up, or say, "Hey, I can't make it - I'm sorry!" right?),
but then we got to working on GNOME.</p>
We had a pretty good turn-out, with seven people there as part of the hackfest,
and one person even showed up to say, "Oh, you are working on GNOME! I don't
like GNOME 3, let me troll you." They initially starting out trolling, but then
we got to talking about the new Legacy session in GNOME 3.8 - and they are
interested! Face-to-face interaction win.</p>
Aside from the initial need to deploy anti-troll measures, it was a successful
event. I worked on Rhythmbox docs, and made six or seven commits to my
gitorious repo, someone else was working on GObject code. He eventually got the
Go-GTK bindings to compile, but had to pull in the entire Go source tree to do
so. He filed a bug. Meg Ford worked on GNOME Documents, focusing on changing
and adding permissions on Google Docs from within the GNOME Documents
application. Someone else (Matt?) explored Lisp-GTK bindings.</p>
As I mentioned, this was our third monthly hackfest, but our fourth one is
scheduled forJanuary 19th</a>. We're
slowly building up a community here, so I think we just have to be patient,
stay focused and give it time. Meg will be speaking on some core GNOME
libraries during the next event - this should be a good talk, and I think the
group will be able to do more collaborative projects once we get a better idea
of everyone's interests and strengths.</p>
Many thanks to the GNOME Foundation for sponsorship of food for the event.</p>


ChicagoLUG hacking on GNOME
Sun, 18 Nov 2012 13:22:42 +0000
The Chicago GNU/Linux User Group</a> had a GNIGHTS and
GNYMPHS of GNOME* meetup and hackfest yesterday. This was the second such
event, and I'd say it went pretty well. I gave a talk on dconf - how it is
similar to and different from gconf, how you can use dconf-editor to manage and
reset system settings, and how you can use the command-line tools to list keys,
read the values of keys, write changes to key values . . . We also had a look
at setting default system configurations with profiles and locks. All in all,
it was a bunch of dconf goodness.</p>
Dee Newcum followed-up with a lightning talk on an application that she's
getting ready to release,
termdetect</a>. It's a utility that
detects the type of terminal to which you are connected. From her gitub page on
the project, it communicates, "directly with the terminal via escape codes, it
doesn't use any other information, so it's much more reliable than $TERM." For
those who know how different terminals can affect your session, this is some
pretty cool stuff.</p>
Aeva Ntsc (who recently implemented 3d printer support on
MediaGoblin</a>) wrapped up the talks with
an overview of Vala. She really likes working with Vala, and her overview was
very comprehensive.</p>
On top of that, it was also nice to see some new folk. Brandi, Chris, and John
showed up after hearing about the event on the website.</p>
We rounded out the day with an afternoon of hacking. I made initial attempts at
creating a quickstart for Mediagoblin on OpenShift, and reviewed sysadmin guide
docs. Meg Ford continued her work on GNOME Documents, and Chris Webber worked
on a MediaGoblin plugin for Shotwell.</p>
Many thanks to Pumping Station: One</a> for being
our host venue (Though I am a member there, but I still feel like I'm getting
use of this great space for free), and to the GNOME
Foundation</a> for providing money for food.</p>
We're planning to have these monthly, with the next one likely on Saturday the
15th of December (though we may take a break for the holiday . . . we'll see).
If there are topics you'd like to present, or something you'd like to learn
about, feel free to share via our mailing
list</a>.</p>
*It's a long story . . . we used to have "Programming Tonight," events in the
city, and I thought up the idea of having Nights of GNOME, which became GNIGHTS
of GNOME, but some people thought it referred to a male GKNIGHT of GNOME, and
we aren't just a bunch of guys, so . . . we may be deciding on a GNEW GNAME for
this event.</p>


Expanding tables and other elements in Mallard
Mon, 20 Feb 2012 08:20:42 +0000
I'm at the GNOME documentation hackfest in Brno, Czech Republic, and we've been
updating help for GNOME platform and applications in advance of GNOME 3.4.</p>
As part of the event, we've been reviewing our use of the Mallard syntax,
making sure that we're getting the most out of some of the new features. One
newer feature in Mallard allows users to expand or hide portions of the help as
needed. This helps users can more easily scan through possible topics, and to
open the ones that are relevant to them. It also has the added benefit of
saving space on the screen. This feature is in an experimental namespace for
now, but we're please enough with the results, and it is likely to be moved
into the primary schema shortly. It will be in limited use in our help releases
for the 3.4 cycle.</p>
Here's a brief example of what this looks like in action (note: you might need
to view the page directly rather than through a feed aggregator if you want to
see the video):</p>
Also, here's a portion of the code that makes it work. All that's required is a
the "ui:expanded" attribute on the appropriate element. It accepts values of
"yes" and "no."</p>
It's possible to use this attribute on any element that contains a title, so
you have the ability to use it on tables (as I've done here), lists, steps, or
even entire sections. Thus far we've only used them on tables, and the style
rules have yet to be ironed out.</p>
The hackfest has been good thus far, but we still have much to do over the next
couple of days. I am focusing on some updates to GNOME user docs, as well as
writing new docs for Seahorse Encryption Manager, Rhythmbox, and am doing some
GNOME docs team wiki work. Florian Nadge and Petr Kovar of Red Hat have been
more than gracious as hosts, and the food on Brno is plenty meaty. Plus, there
is cheap beer.</p>
Of course the food and drink is even less expensive when Shaun McCance of
Syllogist.net</a> sponsors a dinner for us (thanks,
Shaun!). Many thanks, as well, go to the GNOME
Foundation</a> for their sponsorship of our
travel and accommodations.</p>


Documentation and gedit snippets
Thu, 09 Feb 2012 15:37:42 +0000
As I mentioned in a recent post, gedit snippets can help you write code more
quickly, and with fewer errors, than writing all of your code manually.
Snippets work by expanding small chunks of text into complete combinations of
code boilerplate and variable/attribute placeholders. Using these
pre-configured combinations of boilerplate and placeholders frees you to focus
on the bits of code and text that are materially relevant to your work at hand.</p>
You can enable the gedit snippets plugin by selecting Edit > Preferences
> Plugins > Snippets.</p>
There are four components to using snippets: confirming the language or syntax
setting, entering the snippet ID, activating the snippet, and completing the
snippet by entering the appropriate attributes or variables into the
placeholder text areas.</p>
The first thing is to make sure that the file type is set to correspond with
the type of file you're working on. If you're starting from an existing file,
gedit will attempt to set the file type for you automatically. If you're
starting a brand new file, or if gedit hasn't correctly identified the file
type, you can also manually set or change the file type.</p>
Once you have that in place, the most difficult part is actually remembering
the snippets that are available. You can view, edit, and create snipppets using
the Manage Snippets window (see Tools > Manage Snippets). Once you know the
relevant snippet IDs, all you need to do is type a snippet ID, and press the
tab key. The tab key is what activates the snippet.</p>
After you press the tab key, gedit converts that brief snippet of text into a
combination of boilerplate text and appropriate variable or attribute
placeholders. Pressing the tab key again will move the cursor to the next
placeholder area.</p>
Here's an example. I'm starting from a blank page, and am writing a new Mallard
XML file. The snippet ID to start a new Mallard page file is just the word,
"page."</p>
Simple enough! Just enter the snippet ID, press the tab key, watch as gedit
inserts the boilerplate text, and then use the tab key to maneuver through the
placeholder areas.</p>
There are currently snippets for numerous languages and syntaxes, but coverage
of each language varies, and some snippets may not include the most recent
language features. Give gedit snippets a try. If you don't see a snippet
feature that you'd like to use, file a bug in the gedit bug
tracker</a>.</p>


Configure gedit for documentation
Thu, 02 Feb 2012 21:27:42 +0000
I've been maintaining the gedit documentation since the run-up to the gedit 3.0
release, and doing so has helped me to get to know some of the ins-and-outs of
the program. What can I say, it's one of the perks of writing documentation -
you get to know the software that you're documenting.</p>
With that, though, I thought I'd pass along some of the basic configurations
that help me to write documentation more quickly, and in a more
consistently-formatted way.</p>
Here's a quick run-down of some settings that you may find helpful:</p>
View Preferences</strong> - Edit > Preferences > View:</p>

</p>


Check the following items:
</li>
</p>
-   Display line numbers (this helps with locating validation errors)
-   Display right margin at column (80 characters) (breaking lines at 80 
characters makes diffs look prettier)
-   Highlight the current line
-   Highlight matching brackets (optional: I don't use this feature, but some 
people prefer it)
</p>


Uncheck:
</li>
</p>
-   Enable text wrapping (not needed if you're breaking lines at 80 characters)
</p>

</ul>
</p>
**Editor Preferences**: Edit > Preferences > Editor

</p>


Tab Width: 2
</li>
</p>


Check
</li>
</p>
-   Insert spaces instead of tabs
-   Enable automatic indentation
</p>


Uncheck
</li>
</p>
-   Create a backup copy of files before saving (not needed if you're using 
revision control, like git or bzr)
</p>

</ul>
</p>
With regards to plugins, I recommend enabling the dashboard plugin (which will 
be available as part of gedit 3.4, included in Ubuntu 12.04, Fedora 17, 
OpenSUSE 12.2, etc.), and the gedit snippets plugin. In the near future I'll be 
writing up a post about using gedit snippets.
One other neat feature that I often use with gedit is the keyboard shortcut for
moving a line up or down within the text. If you position your mouse cursor on
any point in a line, and then press Alt + Up Arrow, it will move the entirety
of that line up within the text. Pressing Alt + Down Arrow will move that line
down within the text. Simple enough! (The complete list of gedit shortcut keys
is available in the user help, by the way. Just open up gedit and press F1.)</p>
Do you have any suggestions or tips for using gedit to write documentation? If
so, I'd appreciate you sharing them with me in the comments.</p>


Meeting users where they are
Mon, 13 Jun 2011 09:56:42 +0000
With both a two-day conference and a three-day sprint, the Open Help
Conference</a> made for a busy week, but I must say
that it was a success. We had people there from Gnome, Mozilla, OpenStack, Red
Hat, BSD, as well as people who were interested in learning about open-source
help. Everyone had something to share.</p>
Some of our discussions may bubble-up as other blog posts, but a couple of the
presentations and discussions made me think more about engaging users where
they are. They made me think of how we can do more to extended help to people
who use our software in the places that they go, rather than just requiring
them to seek-out help from our help platform.</p>
Twitter as a support tool</strong></p>
For example, one topic that we discussed was using Twitter as a support
platform. Jennifer Zickerman demonstrated Mozilla's Twitter-based "Army of
Awesome</a>" as a facilitator
for user-to-user support. It's pretty cool that Mozilla opens up their support
channels in this way -- users help other users directly, and you only need a
Twitter account to help out. Although you can't always solve a problem in 140
characters, it's easy to point someone to a support article or to suggest other
help resources. In a less formal way, I've also seen members of the Mozilla
documentation team use Twitter to request a technical
review</a> of new help
articles, or to remind people about documentation-related events (e.g.,
reminders for Mozilla's Wiki
Wednesday</a>
events).</p>
Stack Exchange sites: Likes and dislikes</strong></p>
Another approach that we talked about were the various Stack Exchange sites. In
talking about this, we liked how good answers rise to the top (as opposed to
regular user forums where you may need to scroll through rows of posts to find
a solution to a problem) and the gamefulness of the sites. We also liked that
user questions and responses are available for download in XML format under a
CC-by-SA</a> license (albeit with
fairly stringent attribution
requirements</a>). In
particular, the XML downloads of user questions will allow documentation
contributors to see what questions users are really asking, and what questions
are occur frequently.</p>
This being an open help conference, some of us did note that the back-end for
any Stack Exchange site is proprietary, and discussed the network-effect of how
using closed-source tools encourages more people to use to closed-source tools.
Yes, Stack Exchange sites are "free-as-in-beer" to the people who use them, but
we discussed both OSQA</a> (GPL-licensed) and
Shapado</a> (AGPLv3-licensed) as open-source alternatives
that would be worth considering for similar help-site deployments. Someone also
mentioned that Reddit (which isn't necessarily a help platform, but is
open-source software) is a popular area where people can post questions or
comments that are related specifically to Gnome or Ubuntu.</p>
Using blogs and planets to recruit writers</strong></p>
Aside from Twitter-based tools and Stack Exchange sites, some other ways of
seeking out users are less centralized. Two items I took away from Anne
Gentle's talk were that she is not shy about asking bloggers to repurpose their
blog posts for use in the official documentation, and she also recruits people
who post to the OpenStack Planet</a> to help write
documentation. These approaches seem especially helpful when writing
documentation for very technical and complex projects. In some areas, the help
author may not have the deep domain expertise needed to write docs for
bleeding-edge software.</p>
Other possibilities, and the remaining need for good docs</strong></p>
One project that I'm curious to know more about is the Mozilla
Sumo</a> project. I wish that members of
their team had been able to join us. Sumo seems like a well-rounded platform
for gathering user contributions to official documentation, while still
allowing for editorial review and for document translations.</p>
Even with all of this in mind, though, I still see strong, centralized
documentation as very important. After all, it can save a lot of time if a user
can find good docs in one central spot, and even Google isn't helpful if no one
has documented a well-researched solution to a problem. These discussions
reminded me that it's also important to interact with users where they are,
though. If you have ideas for other ways to interact with users where they are,
or know of something that has worked well for you, feel free to share any
suggestions in the comments.</p>


My UDS in photos
Tue, 17 May 2011 22:49:42 +0000
Here's a few pictures from UDS:</p>
</p>
Saying goodbye to Matt Zimmerman at the UDS opening keynote. It took me until
Friday to thank Matt for his advocacy around women's issues, as well as LGBT
and gender issues. There aren't many people in positions such as his who do so,
so many thanks, Matt. Best of luck to you.</p>
</p>
Jani Monoses and and Charlie Kravetz, the past and present leaders of the
Xubuntu project. (Missing in this photo is Cody Somerville, who headed up
Xubuntu in between the two pictured here. Also missing is Lionel Le Folgoc, who
was surely off packaging software somewhere in France.</p>
</p>
The hotel's grand ballroom, with the one and only Micah Gersten (micahg) in the
foreground. He makes us all feel more secure when he's around.</p>
</p>
The bridge on the Danube at night. We had a lot of fun walking around and
taking pictures that night.</p>
</p>
Me giving a thumbs-up to the trip while going down one of the super-escalators
to the train platform. (Credit to Lyz Krumbach for this photo - CC by SA 3.0).</p>
Many thanks to Canonical</a> for sponsoring my airfare
and accommodations on this trip.</p>


Ubuntu documentation at UDS: A summary
Tue, 17 May 2011 22:26:42 +0000
Now that my week at the Ubuntu Developer Summit is over, and I have completed
my safe flight back</a>, I thought I would write up a blog
post about my experience while I complete my recovery from jet lag.</p>
My week at UDS</a> was a challenging week. A great week.
A week in which I had great discussions around docs, met lots of cool people,
and wound up expanding the limits of what are normally considered acceptable
sleep patterns.</p>
I had three docs-team sessions during the week. I also attended two sessions
about cloud-related documentation, and another session on server documentation.
The three docs-team sessions focused on the team strategy, our goals for the
11.10 release cycle, and evaluating a web-based documentation platform.</p>
Team Strategy</strong></p>
The inspiration for the team strategy discussion is the Xubuntu Strategy
Document</a>. Have you read it?
When Cody Somerville first wrote it, part of me was like, "Are you serious? Did
you write this yourself?" It seemed too complicated. In practice, though, I've
seen the Xubuntu team reference that document while making decisions time and
time again. I think a similar document would benefit the docs team, too. I'm
preparing a draft document based off of recent team discussions, and will be
sharing it in the next week.</p>
Team Goals for the 11.10 Release</strong></p>
The team goals session was pretty great. People in the room, and people
listening in via the audio casts, gave helpful input. There was more focus on
the Ubuntu wiki at UDS than I anticipated. Some of our goals for this cycle
include creating a strategy document, contributing to upstream docs projects,
refactoring our team wiki, testing of documentation accessibility, testing a
preferred help layout, doing stable release updates for docs and translations,
squashing boogs, adopting a consistent coding style, updating our style guide
(or picking an existing one), and doing some of the initial work in revamping
help.ubuntu.com.</p>
It sounds like a lot, and it is, but some of it is already a work in progress.
We will make these goals explicit during our next team meeting.</p>
Web-based Documentation Platform</strong></p>
The group behind this project is Pronovix, a Drupal consultancy. I knew that
their project was using Drupal and DITA, but I wasn't sure what *their project
did*. They had some of their staff based in Hungary, just a short trip away
from Budapest, so I thought it was worth getting in touch to learn more about
their approach and how it might benefit us.</p>
DITA stands for the Darwin Information Typing
Architecture</a>, an XML
syntax developed by IBM that specializes in content profiling and content
reuse. The advantage of content reuse with a tool like DITA is that it allows
you to write something once, write it well, and reuse it most everywhere. That
is the idea, at least. Implementation of DITA can be difficult. Their project
has promise, but the toolchain isn't currently packaged by any distro other
than OpenSUSE. Harald Sitter (Mr. Apache Log
File</a>) felt that this very much limits the
likelihood of upstream adoption.</p>
Even with that in mind, we are going to seriously evaluate their platform. It
was very considerate of this group to make a trip to demonstrate their project,
and we want to be supportive of everyone who is working in open source
documentation.</p>
There are quite a few irons in our fire, and we'll have to get word out about
our activities somehow. Our progress will likely be presented via a new Ubuntu
Documentation Team blog. We think now is a good time to start one up, so look
for more info on that soon, as well.</p>


Help for Ubuntu 11.04 - We are working on it
Tue, 12 Apr 2011 16:19:42 +0000
Trying to write documentation for both Gnome 3 and Ubuntu 11.04 had many of the
documentation contributors a bit strapped for time, but we are making progress
on user help for 11.04.</p>
Here is a quick peek at what we are doing:</p>
</video>
This is all done with Mallard</a> and Yelp.</p>
KDE, you can have this, too. Talk with
Shaun McCance</a>. Shaun has revamped the
back-end of yelp so that it wouldn’t be crazily difficult to put a Qt
front-end
on it.</p>
Just imagine it … You could call it “kelp.”</p>
As for the docs, there is still much more to be done. Join us on
#ubuntu-doc on IRC, or join the Ubuntu Documentation team mailing list
to see how you can help out.</p>
j1m.net

West Coast Docs Hackfest - 2019

About

Site</h3> This site is built with Zola</a>, a Rust-based static site generator.</p>

License</h3> All media and text on this website are provided under the CC-by-SA 4.0</a> license unless otherwise noted.</p>

LibrePlanet 2016 - Freedom Sympatico

Reflecting on Feedback

GNOME Docs in Cambridge: Day One

Beyond Clicking: Refactored User Help for Passwords and Keys

I'm on California Time

GNOME CAKE 3.10 - Fully Baked, No Bugs

Flourish Conference

GNUS of GNOME in Chicago, March Edition

GNOME Docs Hackfest - Day One - Complete

Chicagoans and GNOME, Part 3

ChicagoLUG hacking on GNOME

Expanding tables and other elements in Mallard

Documentation and gedit snippets

Configure gedit for documentation

Meeting users where they are

My UDS in photos

Ubuntu documentation at UDS: A summary

Help for Ubuntu 11.04 - We are working on it

Site</h3>
This site is built with Zola</a>, a Rust-based static site generator.</p>

License</h3>
All media and text on this website are provided under the CC-by-SA 4.0</a> license unless otherwise noted.</p>
