Consolidating duplication

Now that 1.9 has been released, I think we need to step back from new features and start consolidating the developer experience. We have a *lot* of duplication in this project:

  • 2 Change logs
  • 2 build scripts
  • 2 sets of documentation
  • 2 PHP test frameworks (Evan made some promising headway)
  • 2 JS engines
  • 2 class loaders

I know some of this is due to BC, but a lot of this can and should be fixed. I think the biggest offenders are the documentation and JS.

For docs, we don't have much of an excuse to have two of them still, other than we haven't had the time to migrate the old one. It's arguable that we shouldn't have launched the RTD version (even though it's an improvement) if we didn't have a time to properly migrate the existing docs.

For JS, I understand we needed to keep our Elgg JS object in 1.9 for BC, but we should have updated our JS to be AMD compatible. It's confusing for new devs to see us recommend using AMD but that not be reflected in our own code.

I know we're all interested in forward momentum toward 2.0, but we've been putting some of these off for so long that first impressions of Elgg to new devs are not what I think we would all want them to be.

  • Issue about the docs: https://github.com/Elgg/Elgg/issues/6812. Let's try to keep it up-to-date (doesn't seem to be at the moment.)

  • Agree with Brett. Unambiguous documentation is important. The best documentation you get, are live examples from core developers' own code, so it should reflect recommendations.

  • Related to this new focus should also be consistency in the code. Things we frequently run in to:

    • Difference in breadcrumb usage
    • Inconsistency in menu names (label) en page titles
    • Not using elgg_view("input/") in multiple places
    • Not using elgg_view("output/") in multiple places
    • html not in views (but in functions)
    • consistent use of elgg_view_form
    • inconsistent rendering of full view pages
    • hardcoded menu items (instead of hooks)
    • incorrect use of headings
    • naming convention for core functions en core plugins
    • fix some unusable functionality (like input/autocomplete)

    Some of these are some major chores and could use a documented statement (or best practice), like the breadcrumb, site titel and menu names.

  • We are kind of stuck choosing between user experience and developer experience at this point it feels like.

  • @evan i don't think so, i think Elgg needs to practice what it preaches, so the code must reflect that. With documenation not being clear at all points, people look at the code to "copy" the good behaviour from the core plugins. As there is inconsistency in the code, in the end, the user experience will have the same issues as the developer (inconsistency in UX)

  • We are kind of stuck choosing between user experience and developer experience at this point it feels like.

    If it's the case that the decision is polarized (I don't think it is), then we need to pick the developer experience. Users can't truly have a good experience if the people responsible for building it don't know how or can't. Elgg is a framework before an end user product, so we have to make sure the framework works.

     

  • I just mean that every moment I spend on converting tests to phpunit is a moment not spent on the Angular plugin. I perceive the angular plugin as providing more bang for buck at this point.

    And of course I am considering the developer experience as I build that out. See the web services API implementation of that plugin to see what I'm talking about.

    But the main goal is definitely to get a good UX with as little effort as possible on my part. So far that's been a reasonable recipe for coming up with a good DX too, as long as everything is well documented...

    For the long term we definitely need both DX and UX, to be sure.

  • Most important thing on your list here is documentation I think, since a framework without documentation might as well not exist.

    Second is JS engines discrepancy because that has resulted in some confusing problems for people.

    The rest are lower priority IMO.

  • The Angular plugin is definitely good work to do, but I don't think it should have higher priority than cleaning up the code and dev resources for a few reasons:

    1. It's a different project that isn't part of core yet, and we haven't had many discussions about how to pull it in. We can't compare it to work that needs to be done for core DX or UX.
    2. Instead of thinking that converting tests is time not spent on a new possible feature, think that it's time ensuring the server side is stable and predictable for the new feature. Currently, none of the SimpleTest suites are run during builds, which is Bad because they test different things.
    3. No new feature should be a blocker for things that needed to have been done already. We don't really have any good excuses for letting these things build up.

    Like I said, I think we need to spend a release focusing on cleanup instead of new features. We've worked so long with all of these idiosyncrasies I think we're a little too used to them and let them slide more than we should. I know if I checked out a framework as a new user and saw some of the stuff we do I'd be turned off. 

    As soon as I get some free time, I'm planning to start tackling the docs.

Feedback and Planning

Feedback and Planning

Discussions about the past, present, and future of Elgg and this community site.