EasyAM

From Info-Ops
Jump to: navigation, search
EasyAM is a tag-based note-taking system. This allows as much or as little detail as desired to be recorded

EasyAM is an Analysis Compiler first developed by Daniel Markham. It converts tagged questions about a particular topic of interest into a map of important conversations that need to occur for a useful product to be produced. It was created to demonstrate practical applications to the concepts found in the book Info-Ops.

The Problem

Analysis is the "work around the work", things that need to be done in order for the work to happen. These all involve questions about specific items, such as "what tools are we using?", "Does this need to be available to the public?", or "What are the training requirements for using this?"

Various tools have sought to capture and track the answers to these questions, but the problem is that no two projects are alike. Creating any sort of tool with forms to fill out implies that they are. This leads the "tool to program the developer", meaning that the assumptions made in the tool are viewed by development teams as being indicative of what they should be doing, since the assumption is that the toolmaker knows more about the work than they do. (An assumption that is true in many other areas, but not this one.)

The Solution

EasyAM solves this by using a tag/compile paradigm instead of a tool/form paradigm. Teams take notes in plaintext format using a text or code editor, then all of these notes are compiled by easyam into a resulting map of where critical conversations need to occur. On some projects lots of notes might be taken by everybody involved. On some projects just a few notes might be taken by one person. There is no requirement for how many notes are taken, by whom, or what goes in the notes. Whatever taken, however, can be compiled to various other documents, allowing the team to Only Handle Information Once.

The recommended way to take the notes is using the concepts and examples provided in the book Info-Ops, although users are free to take them in any way they like.

Initial Applications

Since the compiler both emits tagged text, any tools that consume or produce tagged text can be configured in a pipeline configuration, much the same as any other text tools. This would including piping, copying, batching, translation, concatenation, and so forth.

The version of EasyAM provided with the book provided several sample reporting formats, including ATDD file creation, User Story Cards, web documentation, excel reporting, and a prioritized master question list. The book suggested several other potential applications such as Trello synchronization for tasks/stories, Customer Service Rep auto-documentation updates, and enterprise/program management. In general, a publish-subscribe paradigm is indicated, where people and teams can take as many notes as they'd like at any level of detail, then others in their organization can subscribe to topics of interest.

In the current version of EasyAM under development, reporting has been separated from compilation. The desire is that this will allow a more robust and full-featured integration ecosystem to appear.

Concept of Operations

  • Everything is in a plaintext file. Links are allowed, but everything is readable and in (close to) English format
  • Multiple files are compiled in alphabetical order
  • Multiple mentions of the same thing are fine. They do not create a new instance and instead key back to the original instance
  • To force users to focus on the language and not the data, there no "magic numbers" like in JIRA or Version One. Instead, everything keys off of Title (which must be unique)
  • The compilation "restarts" with scope with the beginning of each file
  • The default output and input are the same. It can loop on itself indefinitely without changing the underlying data
  • Keywords are always in ALL CAPS

Version 0

The prototype was created to assist classroom exercises in 2016 and work continued until mid 2017.

Version 1

Version 1 was created as a demonstration program for the book Info-Ops. Work continued through July 2018.

EasyAM 1 repository

Version 2

Version 2 was started in October 2018.[1]

Version 2 has several design goals:

  • Use of markdown for all freeform text
  • Separation of reporting from from compilation
  • Use of dotnet, Domain-Driven Design, Expecto, and other technologies
  • More thorough test coverage
  • Simpler language format
  • A reporting engine that also uses markdown

The language specification for version 2

Version 2 Development Blog

  • EasyAM 2 repository