Hi.

About a month ago, we started with a major focus shift towards our documentation wiki (at wiki.remobjects.com. Back when we first started the wiki, years ago, it was an innovative step in developer product documentation and provided a level of information and access that few other component and tool vendors offered. A lot of time has passed since, and we felt that a refresh is needed in order to provide even better and more thorough documentation across our products, from Articles over How Tos, and Samples to core Library Reference docs.

This will be a lengthy process, and you won’t see the wiki radically change over night, but instead, all thru the rest of the year, you should see steady progress and steady improvements both to the kind of information we provide and to how it is provided and accessed.

To accompany that, we want to start a (semi-)weekly series here on the blogs where we will keep you informed about what new content (and infrastructure) has been added in the past week (or so). Because we have a bit of a head start, this first post in the series will be a whopper.

Changed, Cleaner Per-Product Sections

The first thing you’ll see when you visit a product page on the wiki is that we’ve restructured each product’s root page (for example DA/.NET into four big categories — indicated by four big icons across the top.

These same 4 sections will greet you for every product, and they are:

Getting Started: Clicking this section will give you a page with a curated, hand-picked selection of articles, how-tos and (external) videos from RemObjects TV, streamlined to get new users (or existing ones) started with the product. For each product, we start with a detailed look at our project wizard(s) and a walk-thru of the project they generate. And we provide a list of How-Tos and articles about common tasks or goals that users will be likely to want to achieve after starting a fresh project.

If you look at these Getting Started pages now, you will still see a lot of red. That is because we purposely started with a blank slate: we did not want exiting content to drive these pages, so instead, we sat down and approached this from the user’s perspective: “What would you want to do next?”, and added the appropriate links. These will now need to be be filled — some by redirecting or reworking existing content, many of them, with fresh content.

Samples: Almost as important as starting a new project is to find your way around the existing sample projects. Each product now has a thorough overview page that covers all the sample applications we ship (for example RemObjects SDK Samples). The different editions of our respective products aren’t islands, and the samples from the different editions often work together or complement each other; that’s why each product has a shared page that covers the samples across all the platforms, where you can see how it all fits together, and, of course, dive into each of the individual samples.

As with the getting started, we have a lot of coverage still ahead of us, but you will see that quite a few samples are already covered.

Articles: For each product, the articles section (e.g. DA/Xcode will provide direct access to all the articles available for that product. We have always had tools in place that helped us manage the wiki and generate pages, and in the past we mostly used that for library documentation (more on that later). We’ve now extended that so that the Articles (and HowTos) sections are completely driven and auto-generated by meta-data in the individual articles. Each article topic in the wiki now contains meta-information on which product, platform(s), categories, classes and concepts it pertains to, allowing us to generate automatic (but designed to be human-readable) index pages. Articles can automatically reference the classes or concepts they refer to, just as the class documentation can automatically get links to articles that touch on a specific class.

We have started this process with a handful of articles — some new, some pre-existing, but reviewed and approved, so the lists will start out small, but over time we’ll be adding more new articles, as well as reviewing existing content and bringing it into the system if it is still up-to-date.

How-Tos: How-Tos essentially follow the same structure as articles, but are shorter topics that focus on individual tasks (“How do do i display my data in an NSTableView?”).

The Getting Started section is, essentially, a selective view into the larger pools of content that are Articles and How-Tos. These two sections show you all content, while Getting Started shows a hand-picked subset.

Library Docs

We’re also working on a brand new infrastructure for library documentation, which we’ll give more focus in a future blog post. In the past, we automatically generated the basic structure of the class reference pages, and then filled them within the wiki. With our new tool chain, the entire class documentation will be maintained externally, and emitted into the wiki automatically — this gives us more opportunities to use this documentation in other ways, too (for example for generating XmlDoc files), in the long run.

More about that, later.

Better Separation of “work in progress”

In the past, work on new pages (or even creation of empty stub pages) was done on the page’s final URL. This meant that when these pages were linked elsewhere, the links would show blue (instead of the red you see for a missing page), but when you clicked them, you got to an incomplete or empty page. That was frustrating. We are changing this now, so that new pages get written in different locations (with a “WIP” prefix in the URL), until they are ready for consummation. This way, we can start adding links to them, but those links will be immediately obvious as not having content yet. Only when the page is ready will it be relocated, and all the links will turn blue.

In some places (such as the automatically generated Articles lists), you will see that we add a blue “(WIP)” behind the red link, so visitors can find the work-in-progress pages, if interested.

New Content

Let us know what you think! And stay tuned to this space for continued updates.