Public API and documentation desperately needed

Hi folks, let me present myself before throwing a couple of (kind) rocks at you:

I am the main developer at Rockalingua (rockalingua.com) and we have been creating interactive content for Spanish teachers working with kids for several years. We developed and maintain our own simple but adapted to our needs LMS.

TL;DR: H5P really needs a good documentation for developers, both for extending and integrating into other systems.

Until now we have been developing our games and interactive content from the ground up, and that seemed kind of silly when I found about H5P. I got really excited. Having a brief look at the code on the repos I was convinced the code has good quality and even thought this is a project I'd love to contribute to, if I have the time. So I started to work on the integration of Interactive Video in Rockalingua (Drupal 7)

Of course some friction was expected, we knew we would have to make changes in our system to make it compatible with H5P.

But, a couple of weeks later, and after jumping over several bumps on the road I found myself looking at this code I just wrote (It is in a script loaded using the hook_h5p_scripts_alter hook on our custom drupal module ):

function getDataForResultsScreen() {
    var iVideo = H5P.instances.find( h5pi => h5pi.libraryInfo &&
      h5pi.libraryInfo.machineName === 'H5P.InteractiveVideo' );
    var validQuestions = iVideo.interactions.filter(
      question => H5P_QUESTION_SUPPORTED_TYPES.includes(question.getLibraryName()) );
    return validQuestions
      .map( q => q.getInstance())
      .map( qi => ({
        score: qi.getScore(),
        maxScore: qi.getMaxScore(),
        answerIdx: qi.getCurrentState().answers[0],
        answerStatement:  qi.getXAPIData().statement
      }))
      .map( qData => ({
        //currentState: qData.getCurrentState(),
        title: getQuestionText( qData.answerStatement ),
        answer: getAnswerText( qData.answerStatement, qData.answerIdx ),
        rightAnswer: getAnswerText( qData.answerStatement, 0 ),
        isCorrect: qData.score == qData.maxScore
      }));
  }
  /**
   * @param {Object} statement
   * @returns {string}
   */
  function getQuestionText(statement) {
    return statement.object.definition.description['en-US'].trim();
  }

  /**
   * @param {Object} statement
   * @param {number} answerIdx
   * @returns {string}
   */
  function getAnswerText(statement, answerIdx) {
    return answerIdx !== undefined
      ? statement.object.definition
        .choices[answerIdx]
        .description['en-US'].trim()
      : 'Not answered'
  }

It's supposed to get the information we need to store on our LMS and also hack into the endScreenBubble and present the student the information in the way we usually do.

This code works great, but ... will it a year from now?

That's my concern. The point I'm trying to make is that there is no clear documentation on this.

So now if I put my CTO hat on instead of my hacker-developer one (we are a really small company so I get to play both roles) I'm not sure I've made the right decision bringing H5P into our system. We are small but thousands of teachers depend on our tools in their classes.

If some months or a year from now some content editor updates the interactive video library will it break our code?

That kind of uncertainty has really killed my initial excitement. We can't not trust a library that has no clear interface and no clear documentation. And I don't think I'm the only one who thinks like this.

H5P really needs a good documentation for developers, both for extending and integrating into other systems. That's the only thing that can communicate trust to companies like us.

Besides, me or others wanting to contribute to the project would really benefit from this. Figuring out how to start working with the library was really difficult for me and I consider myself a more than ok javascript developer.

Hope this helps to convince you to bump priority on documentation over features. I really think it would pay off in the mid-long term.

All the best,

Oscar