user friendly tools for describing an element on a html document

Question

I've taken on a new project that's already been in development for some time. The development team and project managers have a good issue tracking system in place and are generally good people to work with but I'm finding it hard to follow legacy issues and understand exactly what people are talking about. This is partly because I am new to the project and it's of a fairly large magnitude but also partly due to vague descriptions of technical problems.

I want to know if there are any simple tools available to exactly describe an element that exists in a html document or languages that help describe specific problems for developers. XPath seems like a good starting point. This must be easy for project managers to work with, not just developers. Usage Scenarios are another tool I can think of that might be relevant.

Answer 1

There is a good tool to describe specific problems in a very exact way: It's called "programming language". The problem is that even simple problems ("doesn't work") are only hiding a complex problem that really wants to get out. See my elevator example how simple problems can quickly turn into a nightmare.

So in your case, you have several problems to solve:

• You're a beginner who doesn't know his way around. Only time and dedication will solve that. There are no shortcuts when it comes to learning a complex system (otherwise, it would a simple system).

• If you need to address a specific element in a HTML page as a developer, I suggest this algorithm:

  list = new List();
  while (element != null) {
      String s = element.name;
      parent = element.getParent();
      if (parent != null && parent.getChildren(element.name).size() > 1) {
          s += "[" parent.indexOf(element) + "]";
      }
      list.insert(0, s);
      element = parent;
  }
  return list.join(";");
  

  This gives a short string which uniquely identifies each element in an XML/HTML document. Works perfectly for a developer, useless for a user. Which leads us the last part of your question.

• There is no tool which works equally well for users, project leads and developers. Why? Because if it would, then one of them could do the job of the other. That's why we develop in teams: People can do different things. A project lead should understand the developer but he shouldn't be better. If the user could understand and write the code, why would he need a developer?