HistoryViewLinks to this page 2012 August 16 | 02:16 pm

We have a variety of publishing systems available to us on open-services.net. Here’s a basic outline for when to use each.

(Migrated from the legacy wiki: Source document)

Contents


open-services.net Wiki

The wiki is the primary collaborative platform for OSLC workgroups.

To be able to edit most of the wikis, you must become an OSLC Member and complete a Workgroup Participation Agreement for a workgroup. See the participation faq and the list of legal agreements.

Spec development

The wiki should always be used for workgroup activity and specification development, including the following:

  • Workgroup homepages, lists of members, etc
  • Workgroup meeting minutes and schedules
  • Working and completed documents for workgroups or specifications (scenarios, resources, supporting documents)
  • Human-readable versions of specifications
  • Content that pertains to only one workgroup

Working or collaborative documents

The wiki is the ideal environment for working documents where you are expecting multiple people to edit, review, contribute to, or improve them over time. This is a wiki, after all.

The wiki has a system for comments, but it’s almost never used; it’s not prominently displayed, and I don’t believe most people even assume that a wiki would have open comments.

If you’re looking for feedback or contributions for a wiki page, it might not be a bad idea to post in the forums or request a blog post to increase awareness.

Minor file hosting

In a pinch, you can upload files to the wiki by attaching them to a page.

We do not have unlimited space, so please don’t abuse this.

The open-services.net Blog

The blog currently has one author (your humble webmaster [YHW]); however, I am working on tools that will allow anyone to submit blog posts directly.

In the meantime, if there’s something you would like to see on the site blog, contact Lee.

The blog is a useful catch-all for the following types of content:

  • Community news (which it replaced)
  • Announcements (software, specification advancements, events, new members, etc)
  • Community rabble-rousing: calls for submissions and requests for feedback
  • Linking to articles, blog posts, or discussions (happening on our site or elsewhere) of interest to the community
  • Opinion/”Think” pieces
  • Very short tutorials or quick tips

Admittedly, I have some concerns that the blog could become an “anything bucket” for all sorts of random content; I’m not sure yet if that’s a good or bad thing.

<Comments_KK>I have concerns here about the blog being a catch all thing, the other thing that bothers me is that, there should be guidelines on how people publish their personal opinions, it not be offensive to anyone, there needs to be a proper decorum that needs to be established how people post this type of content </Comment_KK>

<Comments_LJR>What I mean by “catch-all” is I have a suspicion that with multiple authors and frequent entries, it’s inevitable that the blog will have a variety of content. I don’t think that’s a bad thing: most blogs have at least a minor element of randomness – call it “flexibility” if “randomness” leaves a bad taste. And I think having a place that’s official-like (as part of the front site) but with less strict content guidelines is going to be a useful thing to have available to people.

I will be writing up a style/voice guide for people to heed while writing blog posts. But with multiple authors there will have to be a balance between their unique voice, which I don’t want to squelch, and “OSLC Voice”. And if I have to clarify “Don’t be offensive”, I’m going to cry.

But I am also not naive: as I lay out below, submissions will be moderated.</Comment_LJR>

Someday: workflow for submitting blog entries

The eventual workflow for others to create blog posts will be as follows:

  1. Create an account on the forum and log in. The ability to write and edit blog entries will only be available to logged-in members. (The forum and the blog use the same back-end system)
  2. I will have a page for you to write a blog entry. I will have a style guide eventually.
  3. When you submit a blog entry, it will enter a “review” state and it will NOT be available on the site immediately. YWH will receive a notification.
  4. YWH will review the entry, make edits for clarity and style (he’s persnickety!), and if necessary bug you for clarifications or additional information.
  5. YHW will publish the blog entry as a draft. It will be invisible to the public, but accessible to logged-in authors. YHW will send you a link to review the content.
  6. You can review the content and see a big button to “Approve”, at which point the blog entry will become “live” and visible to the public. You will have the ability to make edits before (and eventually after!) the entry goes live.
  7. If you make a substantive edit after the post is live, it’s good karma to note the revision (as an Update/Correction) in the post itself.

open-services.net Forums

The forum (which is still very new) is an entryway with relatively low barriers ( especially for relative newcomers) to ask questions and get (hopefully prompt!) feedback. People could use the mailing lists, but forums have better search, provide more flexible organization, and require less commitment, which can be very appealing.

To post in the forums, register here.

The names of the subforums there should pretty well cover the content that I believe belongs on our forum:

  • questions about OSLC
  • post news that the community might find interesting (this might get replaced when I build a tool for others to create blog posts)
  • discuss posts on the blog
  • discuss details about the site (meta)
  • propose new specifications
  • discuss OSLC-compliant software (technical Q&A)

If you’re someone who frequents the wiki or is heavily active in the mailing lists, forum is best thought of as “not for us”; if you have access to other tools (site, blog, wiki), you’ll probably find them more appropriate. The forum is an open discussion board for people that can’t so easily make their voice heard.

Polls

You can do polls on the forum; keep in mind that they’re not terribly advanced.

Brief case study: W3C FAQ

As an example of not-great use of the forum, I (YHW) posted an FAQ about the W3C trial in the forum; in retrospect, this was better classified as official documentation or a work in progress; it probably would have been better to write that as a blog post or (even better!) on the wiki and then open up a thread to encourage discussion in the forum.

A high-level page on open-services.net

Current content

Here’s the content that currently exists on the “front matter” of open-services.net:

Coming soon, there will be

  • Individual pages for members
  • Individual pages for software
  • Individual pages for specifications/workgroups

And some content I would be thrilled to add eventually:

  • Events such as upcoming conferences (dates, attendees, location, etc)
  • A tutorial about best practices for workgroups (codifying the content here: Workgroup best practices)
  • Testimonials: what problem did OSLC solve for you?

Goals of the front-facing site

The front-facing site is tasked primarily with gathering and combining information, building and presenting an extensive network of relationships between many types of content, quickly sending visitors with differing goals to the appropriate final destination, concisely describing our community, and evangelizing its workgroups and their output.

Guidelines for content

So, here’s the sort of content that I want on the front-facing site (excluding blog posts, discussed above):

  • Be generally useful to the entire community
  • Be of particular interest to people that are new in some way to some aspect of OSLC (There are different types of ‘newness’: eg you might have just heard about OSLC, you might have just been tasked with implementing a specification in some software, you might have been involved with the community for a while but now want to start your own workgroup).
  • Highlight the creations of workgroups or members
  • Weave together disparate content from many sources (see About/Participate/Resource pages)
  • Tell a story, especially that illuminates what the members or workgroups are doing (testimonials would be great here)
  • The content does not better belong in any of the other aforementioned tools
  • Require special layout or functionality not offered by the other tools (eg multi-page tutorials, custom layouts, forms, etc)

I’ve set the bar high here on purpose. I do not want every little bit of content to get its own page on the front-facing site. The front matter is a first impression and must be crafted, professional, organized, concise, authoritative, and reliable.

Do you have an idea that fits that bill? Let’s talk.