Documentation Team

Shaun McCance has announced the release of gnome-doc-utils 0.17.2:

I've just released gnome-doc-utils 0.17.2, which includes
all the build magic for Mallard documents.  Using it is
similar to using the DocBook build magic, except:

1) You don't use DOC_MODULE.

2) Set DOC_ID to a system-unique identifier for the document.
This will determine where your document is installed.  For
instance, if "DOC_ID=empathy", then your document will go
into "/usr/share/gnome/help/empathy".

3) Set DOC_PAGES to the list of page files in your document.
Just as with DOC_ENTITIES or DOC_INCLUDES, do not include the
leading "C/".

DOC_ENTITIES, DOC_INCLUDES, DOC_FIGURES, and DOC_LINGUAS work
exactly as for DocBook documents.

We need to work on xml2po some.  Its default operation isn't
producing the best results for Mallard documents.

Those of you working on Mallard documents, please hammer on
this and let me know if you have any problems.

The Documentation team is having a team meeting tomorrow, Sunday June 28th at 9:00 p.m. UTC / 5:00 p.m. EST.

The meeting will be held in the #docs channel on GIMPnet IRC.

The agenda can be found here on our wiki page.

See you there!

The GNOME Docs Project has two meetings coming up this week.

Wednesday, June 24th at 7:00 p.m. UTC: Community Meeting

Have a question for the docs team? This is the place to ask any question you might have, such as:

• What was (and what was discussed) at the Writing Open Source conference members of the doc team recently attended?
• What is Project Mallard and why is it important?
• What is the difference between topic based and task based documentation?
• How can I get involved?
• I submitted a bug in Bugzilla, why isn’t it fixed?
• How can we make docs sexy?

This is the place to come.  Look for Paul Cutler, Milo Casagrande and Phil Bull in the #docs IRC channel on GIMPnet.

Sunday, June 28th, 9:00 p.m. UTC: GNOME Docs Project steering meeting

This meeting will discuss the project structure, roadmap for the documentation team and it’s tools including Yelp and gnome-doc-utils, GNOME 3.0 planning and more.

All are welcome to attend, though the meeting will be moderated, and the formal agenda will be posted to the wiki (as well as the minutes after the meeting) in the next few days.

I’ve just released Yelp 2.27.1, Now With More Ducks. This coincides with gnome-doc-utils 0.17.1, Also Now With More Ducks.  This marks the first release with Mallard support built in.  And this marks the end of the boring part of the release announcement.

This is a huge shift in how we approach, plan, write, and generally work with documentation.  The entire community needs to be aware of what’s happening and how it affects them.  Fellow hackers, please skip to the bottom for information on how this affects you.

Mallard is a new[1] documentation format that is geared towards topic-oriented help.  While you could, in theory, just convert all of your DocBook documentation to Mallard, what you would end up with is a document that is the worst of both worlds.  Writing topic-based help requires a new way of thinking about how we present information to our readers.

Mallard is uniquely designed from the ground up to support downstream modification and plugin-based help systems with little to no patching.  The dynamic organization structure of Mallard was designed with our help in mind, addressing the challenges we face as an upstream provider.

If you’re interested in writing, editing, reviewing, or otherwise contributing to our documentation, please get in touch with our team.  You can email use at  gnome-doc-list@gnome.org or join us in the #docs channel on irc.gnome.org.  Also, check out our brand new project blog:  http://blogs.gnome.org/docs/

We will be holding regular community meetings.  Stay tuned for more details.

If you are a maintainer or active developer, know that we are coming for your documentation.  It might not be today, but it’s on our radar.  If you or someone on your team handles your documentation independently of our team, we still want to be in contact to help them produce better help.  Writing is not a one-person task.

We hope that developers will be cooperative with our team as we try to provide them with better help files to make their software better for their users.

We also hope that more people from the greater community, including our downstream  communities, will get involved with our team.  We are doing some truly exciting things right now, and we’d love to share the excitement.

Fearlessly,
Shaun

The GNOME Docs Team will be having a question and answer session in GIMPnet IRC, channel #docs, at 9 p.m. CST (2:00 a.m. UTC), Thursday, June 18th.

Shaun McCance and Paul Cutler of the GNOME Docs Team will be available to discuss their experiences at the Writing Open Source Convention last week, as well as answer questions about GNOME Documentation you might have.  If you have questions regarding how to get involved, writing, editing, planning, tools, or if Project Mallard even really exists, we’ll be ready to answer them.

If you have ever wanted to get involved with writing for an open source project, now is a great time to get involved.

We look forward to seeing you there!

Next week’s Q&A session will be June 24th, 7:00 p.m. UTC (2:00 p.m. CST).