Is XML coding documentation dead?

form-design

(Greg Pommen) #1

Hi, Now that all the form design documentation has been centralized on https://docs.opendatakit.org/ I can't seem to find any of the documentation anymore that had the raw XML code on it. It's all XLSform based now. As someone who learned XML coding years ago for ODK, when XLSform was still pretty limited, I'm hoping the raw code is somewhere. There are things I can't seem to find very easily on the Open Data Kit documentation site. Is it still stated or do I have to start learning XLSform from scratch? Once I learned the XML way of doing things, XLSform just seems like another step. Thank you!


(Adam) #2

This has been a bit of an ongoing conversation, so I'm glad for your input here.

The general thinking has been that docs.opendatakit.org woud focus on XLSForm, and that we would not support encourage editing XML directly. A couple primary reasons for this:

  • the number of XForm features supported by Collect but NOT supported by XLSForm and its tools (pyxform, etc) --- that is, things that would require XML editing directly --- is minuscule and shrinking.
  • editing XML "by hand" is error prone, and we don't really want to encourage people to think it is the best path to building forms

That being said, a few points about the future of XML-focused documentation...

  • The primary XForms documentation is the ODK XForms specification. This still exists, and will continue to exist.
  • That documentation is under active development and is currently being improved. (I believe there is currently a grant in process to improve it, but I can't find details to link to. I'll let another community member fill in here.)
  • The existing/old XML-focused documentation that was on the old ODK website before the recent update was almost entirely duplicated information that now exists in the spec.
  • That said, it is an open question how much docs.opendatakit.org should expand on the specification docs to provide more "user friendly" information and tutorials around working directly with XForms. Some of the specific questions have started to manifest as specific XForms-related issues in the docs repo. You are very welcome to participate in this ongoing conversation or to contribute directly to the docs. (In fact, I'd love to have someone with deep XML/XForms experience helping out with planning and authoring this content.)

(Greg Pommen) #3

Hi,
Thank you very much for your response! I'm very glad to find https://opendatakit.github.io/xforms-spec/ exists!

I'm not sure how my experience with XML/XForms rates, my programming knowledge isn't extensive, but if I can help, I should. How would I go about doing that?


(Yaw Anokwa) #4

Here's what I'd recommend...

  1. Review the existing spec and see what, if anything is missing or preventing you from doing your work.
  2. For things are missing or unclear file issues.
  3. Send in PRs to fix those issues.

(Greg Pommen) #5

Thank you Yaw. What is a PR though?


(Yaw Anokwa) #6

:blush: Sorry, I shouldn't use jargon. PR is a pull request, which lets you tell others about changes you've made that are ready to be added to the main project.

At a high level, when you want to make a change in ODK (including docs, website, spec), you make a copy (a fork) of the main repository, then you make the changes in your fork, then send in a notice (a pull request) to the original repository. Once the pull request comes in, a maintainer will review it and merge it into the original.

https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github has a decent write up of the mechanics but let's not worry about all that just yet.

Let's start with Steps 1 and 2 and when you are ready to add to the spec, there will be plenty of people to help with Step 3!


(Greg Pommen) #7

Thank you very much ... again! I have much to learn. :slightly_smiling_face: