Preview of upcoming static site's content & structure


(Michael Downey) #1

Hi @website-wg and other interested folks! Some updates on the web site for your review. After quite a bit of content cleanup, merging, and formatting, we've got something to review. (There was quite a bit of messy HTML out there to mangle the automatic markdown converters!)

TLDR: This week, I'd like to hear your feedback on the proposed static site structure & content, in parallel while we finalize look & feel. Read on for details.

The content test site is available at http://odk-dev.osc.dial.community/ (now at http://staging.opendatakit.org) for the time being. Please load it up in your browser of choice and take a look, and respond to this post with your feedback. But first ...

Things we needn't worry about quite yet:

  • Layout themes
  • CSS stuff: General font styles, color schemes
  • Non-content (decorative) images
  • Any weird remaining minor mangled formatting that looks like it got caught in the conversion(s).

In other words, let's focus on the content & substance right now, over the look & feel. Things I'd love to hear your feedback about here in this topic include:

  1. Is the structure of the content right, or close to it? Between the two sites, there was a lot of work merging and trimming content. Much of the total content was out of date, and much has already been moved to the Sphinx-based documentation site. I admit that I'm coming to this as a bit of an outsider, so please make sure I'm on the right track about where stuff needs to be.

  2. Are the main sections (About ODK, Software, Support, Download) structured in a logical way? Is there any important content missing? Right now, much more ODK2 content is available on the website than ODK1, as much of the ODK1 stuff has moved to the docs site. (So ODK2 folks, please take a look at the Version 2.0.2 documentation structure before we move forward!) Overall, it feels a little imbalanced for now, but I've tried to link directly to the docs site where appropriate.

  3. Are there important changes to be made to the content, where it has been changed? For example, the front page has synthesized content from several places, as well as had some rewrites by me. The same holds true for the downloads page. In other words, are there any important factual inaccuracies?

Next steps:

Later this week, while hopefully getting feedback on the above questions, I'll prepare some alternative looks, color schemes, etc., for review & impressions. It's important to remember that we're only looking for a good starting point right now -- we can easily make continual design improvements & changes as time goes on. More on the design discussion in the coming days.

Thanks for your help, feedback, and comments! (Once again, for now, please provide your feedback and concerns here as a reply.)


(Hélène Martin) #2

Thanks for taking the lead on this, @downey!

I don't think there should be any documentation on the website. I believe the documentation pages that are currently on the test site are either deprecated (XML-based form design), folded into the documentation site already or pending a decision on how they will be reworked in the future. I was expecting high-level text about what the suites are and their basic tools and then prominent links to the doc site(s).

Donations are mentioned several times. Has this been a source of significant funding? With the UW no longer being the "home" of ODK, does the donation page even make sense? Either way, I don't think it should be a top-level item.

I'm unclear on what goes in Software vs. About or Get Help.

About, Learn, Participate, Download (or About, Documentation, Community, Download or About, Get Help, Get Involved, Download) are the top level items I'd tend to go with.

I've mentioned this before but I'd like to see the words "data collection" more prominently in the most visible landing page text.

The word "family" for ODK1 or ODK2 is new to me. I have a slight preference for "suite."

Is that the level of feedback you want or is it too detailed for now?


(Michael Downey) #3

Hi @LN, thanks for your feedback; it's great! A few responses to further the discussion!

I think consistency here would be great too. Folks like @W_Brunette & @Jeff_Beorse et al., what are your thoughts on how quickly ODK 2 documentation could be integrated with the existing docs.opendatakit.org site? I know this is a big ask. I know some work has already happened, and we may be able to benefit from translating the Drupal WYSISWG-generated docs into static pages, too.

For ODK 1, the Form Design documentation was not yet marked as deprecated, and it's not clear if it's already covered on the docs site. While it's not the end of the world to leave it on the ODK. org web site, it'd be great to consider a move for it, if there's a clear plan for what to do with it.

I think this is a good question for the PMC, but it may not be an easy one to solve. There may be an open question as to what UW can do with donations and how they are managed, if they are able to continue to accept those donations in this "new era". I would caution against having nothing mentioned on the site about financial donations:

While it sounds a bit crazy, it is not unheard of for potential benefactors to roam around looking for projects to support. I know a handful of these folks who regularly look for potential donations (although small) on behalf of their companies & make recommendations. Those folks admit that they will quickly move on to the next project's site if it doesn't look like the project has any use for funds because they're not asking.

One head of open source at a very famous Bay Area tech company that produces tools for open source projects once literally told me, "I never knew [Project X] needed funding, they seemed to be doing so well based on their web site and they weren't asking!" Needless to say, the person with me from Project X put up such a page the next day.

Ultimately this is more of a strategy question. Another option is to leave the donation page but instruct folks just get in touch with the PMC via email. (That's what Project X did, at least in the short term.)

The difference in "About" vs. "Software" is that one is about the community & its back-story, while the other section would be specifically about the software products we all create. If there becomes less need for product-centric documentation, I agree that the "help" and "software" sections could be combined.

Notwithstanding future renaming plans for the ODK 2 tools, is there any canonical naming strategy written up anywhere? There were several different phrases used around the various documents, such as "tools", "suite", "collection", "software applications", etc. I agree it's pretty valuable to aim for some more consensus around short-term naming conventions. What do others think about the names?

It might be wise to do a poll or two to gather more feedback, but I'd like to hear what the rest of folks have to say too. :slight_smile:

Keep the feedback coming, all. Thanks!


(Jeff Beorse) #4

Hi all,

First off, thanks to @downey for all the hard work you've put into this. I'm glad to see this moving along.

Folks like @W_Brunette & @Jeff_Beorse et al., what are your thoughts on how quickly ODK 2 documentation could be integrated with the existing docs.opendatakit.org

I have actually already translated all of the ODK 2 documentation from Drupal into Sphinx (see PR #480). We can safely remove all the documentation for ODK 2 from this proposed website and structure the "Software" page similarly to the ODK 1 section. I believe the current delay is figuring out how to have ODK 1 and ODK 2 documentation coexist, with the leading idea that we host multiple docs sites out of the same repo. As for how long it will take to integrate, I believe that task is being handled by @adammichaelwood.

Notwithstanding future renaming plans for the ODK 2 tools, is there any canonical naming strategy written up anywhere?

I don't believe there is an official stance anywhere. I know in the ODK 2.0 documentation and publications the most common usage is either "ODK 2.0 tool suite" or a shortened variation with just "tools" or "suite" as context dictates.

As for my feedback:

The page used for the root level ODK 2 description is copied from this page, but I think there is good information on this page too. I created mashup of these two pages for the docs site which you can see here. Would my mashup, or something similar, work as a landing page for ODK 2? I am also interested in the opinions of @W_Brunette @clarice_larson and other ODK 2 folks.

I also removed some old stuff that's not useful anymore. Most notably: "Release Designations" are a holdover from ODK 2's pre-release days which are not relevant anymore.

After the ODK 2 documentation is merged and available, I think the "Get Help with ODK" page should link to it.

Overall I think things are looking good and we are heading in the right direction. I particularly like the home page.


(Waylon Brunette) #5

I'll start with a clarifications/answers post.

I would slightly revise this to a goal of "minimal" documentation on the website, as @LN points out there should be basic descriptions (which some might argue is documentation). My understanding of the trajectory we have been moving towards is the majority of documentation in Sphinx. My thought is the website should act as landing page with brief descriptions and direct you to the forum, the documentation site you need, etc.

As @Jeff_Beorse said the ODK2 documentation has already been ported to Sphinx (see PR #480).

Splitting the documentation into different URLs is the same issues discussed here:

Based on the thought to have separate URLS for separate audiences I think it makes sense to have 4 URLs for documentation (developer vs user, ODK1 vs ODK2) with the updated website acting as the main landing page.

AND

Donations through the web have not been a significant source of funding. Historically it has not been enough to covered our hosting costs. There were more donations when ODK first started; however, it has fallen to like $75 a year last time I inquired.

As I recall, the last time the PMC discussed the donation issue we decided not to prioritize trying to find a non-profit replacement vehicle as the amounts were small. Once the final decision is made about the final organizational form of ODK by the transition board (whole concept note discussion, etc) it would probably become clear how best to setup a new donation system and whether that system could still be tax deductible. The one nice thing about UW handing the donations is that they handle everything including IRS reporting and then put the money into an account (as @downey notes does have certain governmental restrictions).

I do not think there is an official guide written up, might be a good thing to do. Here is a brief list or terms that we started trying to use to avoid confusion.

  • Tool - This refers to a packaged piece of software that person will use to perform a task. Tools can be mobile, PC, or cloud based. Examples include Collect, Briefcase, Aggregate, Services, Suitcase.
  • Tool Suite - A set of compatible tools that can be used interchangeably. For example both Build and XLSForm perform similar functions and are both part of the same Tool Suite. Examples of separate tools suites: ODK 1 vs ODK 2.
  • Application - The special use or purpose to which ODK is being used. Basically, The usage of software tool(s) to solve a problem. For example ODK can be used as Polio data collection application or a Malaria data collection application.
  • App - An Android native executable application (software that runs on Android). Examples: Collect, Survey, Tables

(Yaw Anokwa) #6

Great job, @downey!

I think there is consensus on the minimal website that points people to the right places. And the structure and the content are pretty close.

What makes sense to me as far as the main sections are

  • About - Short history of the project, pointers to governance, contact.
  • Documentation - Long description of suites. Links to the various docs.
  • Download - Short description of suites. Links to the various binaries.
  • Community - Links to forum, twitter, chat, etc. Explanation of what goes where.

As far as the content, the high-level description of the suites is pretty good. I think we can probably drop Press, Deployments, FAQ, and SHA Signatures. I also think we should drop Donation for now. The PMC can add some language around that later.

I like @W_Brunette's use of tool and suite. I do not like the use of application. It's too overloaded of a word and I think it's likely to confuse. Maybe @adammichaelwood has some ideas here.

One thing the site is lacking is some way to have some News about the project. That seems important. Any ideas on how we could do that? Or maybe we just point people to the forum?


(Michael Downey) #7

Hey @yanokwa thanks for your feedback, as well as that from @W_Brunette & @Jeff_Beorse. One specific thing I wanted to respond about, as I've been doing some work on this for another project:

One consideration would be to use the blog section (yes, it's currently called "Blog Archive") to post news alerts, but -- and this is where it'd be different -- it can be linked to the Discourse forum for comments and follow-up. A potential workflow for this might be:

  1. Create a "blog post" static page & deploy it to the site. Include the Discourse JS comments code at the bottom of the post.
  2. Load the deployed page in the browser, which would create a "mirror" post on the forum, in a category to-be-specified, such as #announcements.
  3. If folks wanted to reply to the news with comments, the top comments from each news item (topic on Discourse) would be rendered at the bottom of the page.

See https://blog.codinghorror.com/to-serve-man-with-software/ for an example. This above scenario presumes that you are interested in people responding to and/or interacting with the news item(s). Also it of course would require appropriate permissions on the Discourse category.


Another alternative is to work on embedding an RSS feed of a Discourse category (or the entire forum!) on the web site. This is a little bit more complex as it'd require parsing of the RSS feed(s) but if you just want to point people to "the latest news" it might be the way to go.


Social links on new web site?
(Yaw Anokwa) #8

I :heart: this idea because it can pull people into the forum where most of the community lives.


(Michael Downey) #9

From the community engagement side of things, I like it too. That said, it would mean not killing off the blog altogether... :slight_smile:


(Adam) #10

I like @W_Brunette’s use of tool and suite. I do not like the use of application. It’s too overloaded of a word and I think it’s likely to confuse. Maybe @adammichaelwood has some ideas here.

But what if you don't like my ideas?

Suite is a good word to describe the collection of tools. Tools is a good generic term. But I wouldn't shy away from application for things that really are applications. Collect and Aggregate are applications. Pyxform is a tool. (All applications are tools. Not all tools are applications.) I'm not sure exactly where the line is (especially for the ODK2 suite, which I'm less familiar with). But --- I wouldn't rule out application.

I do think "Suite of Tools" captures the collective sense of each thing --- I wouldn't say "Suite of Applications". Based on my limited understanding of ODK2, I might call ODK1 a "Collection of Tools" and ODK2 a "Suite of Tools" --- that captures a bit the fact the ODK1 tools are interchangeable with other non-ODK XForm-based tools in the ecosystem.

Like @LN, I'm concerned by the word "family*, which doesn't seem right. I imagine it translating poorly as well.

I also think it is odd to see ODK1 and ODK2 described in different words:

ODK 1 tools are designed to be easier to use, require less setup, and are widely adopted.
ODK 2 software is better suited for complex longitudinal studies and requires more technical skills.

Is ODK1 not software? Is ODK2 not tools?

This sort of thing is commonly the result of a desire to not repeat words. But it can impede clarity, and often subtly suggests to readers that you really did mean something different when you used the different word. (It can also confuse translators.)

[Updates via blog feature with integration to discourse]

Yes. I think this is a better idea than the other options I can think of:

  • not having comments
  • using Discus or another SaaS provider

(Adam) #11

I don't see any reason ODK shouldn't have a blog. Even if it's just announcements etc.
But it doens't have to be a blog. The blog feature can be called "News" or "Updates"

This can even be separate from the Blog archive. Not sure which tool you're using (Jekyll?) but most have facility to handle more than one collection of post-type content.


(Jeff Beorse) #12

But I wouldn’t shy away from application for things that really are applications. Collect and Aggregate are applications. Pyxform is a tool. (All applications are tools. Not all tools are applications.) I’m not sure exactly where the line is (especially for the ODK2 suite, which I’m less familiar with). But — I wouldn’t rule out application.

Unfortunately I think the term "applications" becomes more overloaded with the ODK 2 tools. In ODK 2, you will find yourself with a collection of web files (HTML, CSS, and Javascript) as well as XLSX forms and possibly other supporting files, that together as a unit are consumed by the ODK 2 platform to render your data collection and management experience. Furthermore, you can have multiple parallel experiences on the same device simultaneously (such as Waylon's Malaria and Polio example). We have struggled to find a word that fits this scenario better than "data management application" or "application" for short.

This, of course, conflicts with the fact that ODK Tables is also an "Android application" which still shortens to "application". In the ODK 2 world we've tried to make this distinction by reserving the word "applications" to mean "data management applications" and the word "apps" to mean "Android applications". I frankly think this has been a losing battle, but I don't know a better alternative either. I wonder if anyone has any solutions to this issue.


(Yaw Anokwa) #13

19 posts were split to a new topic: Should renaming come before the website launch?