Tag: Yelp

So I’ve begun picking Yelp apart in preparation for Yelp 3.0.  I’ve gotten to the broken-eggs stage.  It still doesn’t look like an omelette.  I have a lot of goals for 3.0, including providing a reusable documentation-viewing widget for other projects.  But one of the cool things I’ve been hacking on today is a combined location and search entry.  It’s still very much a work in progress, but I wanted to show screenshots anyway.

When you’re on a page, the location entry will show you what page you’re on, like so:

You can click the drop-down arrow for a history of where you’ve been:

If you click in the text field, you can type in some search terms:

And when you activate a search, it becomes a location in your history:

It still needs some polish, and I need some icons so I don’t have to abuse the search folder icon.  And it definitely needs some usability testing to see if its functionality is discoverable.  Help viewers can’t afford to have a learning curve.  But it’s been fun to play with so far.

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.

[1] Yes, I realize I’ve been quacking since 2004. But it’s newly released, and that counts for something.

♫NP: When This Is Over by China Forbes from ’78