Uploaded image for project: 'Metadata Aggregator'
  1. Metadata Aggregator
  2. MDA-93

MDA pipeline documentation should be independent of Javadoc

    XMLWordPrintable

    Details

    • Type: Documentation
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: 0.7.0
    • Fix Version/s: None
    • Labels:
      None

      Description

      The current MDA documentation is not very easy for people to understand. The Javadoc is available, but that's not really helping users to know how to use each stage and how to wire them together to achieve different effects. Even understanding the relationship between Javadoc API documentation of methods and spring bean properties isn't obvious to most people using MDA for the first time.

      I think a better long term approach is more conversational documentation of the individual MDA stages on the web site. This might point to the Javadoc but as reference material only. Instead, for each stage, we'd have a separate page including:

      • the stage's class name
      • a brief statement of purpose
      • property definitions
      • at least one and often more examples of bean configurations for the stage, sometimes in combination with other stages

      We could even use (whisper it!) diagrams for more complicated setups like the branching and merging stages.

        Attachments

          Activity

            People

            Assignee:
            ian@iay.org.uk Ian Young
            Reporter:
            ian@iay.org.uk Ian Young
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated: