Documentation Hierarchy

Discussion on the documentation for SJTAG
User avatar
Ian McIntosh
SJTAG Chair
Posts: 504
Joined: Mon Nov 05, 2007 11:49 pm
Location: Leonardo, UK

Documentation Hierarchy

Post by Ian McIntosh »

In response to the action from the June 4th Meeting, I'll start the ball rolling with the following proposition for a document hierarchy:
  1. Overview Document
    • Scope of SJTAG
    • Purpose of SJTAG
    • Primary constraints
    • Relationship to other standards
  2. Use Case Document
    • For each Use Case:
      • Application field(s)
      • Detailed description
      • Alternative techniques (comparison)
      • Tooling requirements
      • Value proposition
  3. Languages and Data Formats Document
    • Languages for test flow and control
    • Formats for exchange of device programming operations
    • Formats for exchange of test vectors
    • Formats for exchange of result/diagnostic data
  4. Hardware Architectures Document
    • External and Embedded architectures
    • Chain topologies
    • Gateways
    • Tooling requirements
This is very much an initial one-man brainstorm, so please feel free to pick this apart :)
Last edited by Ian McIntosh on Tue Jun 17, 2008 6:57 am, edited 1 time in total.
User avatar
Bradford Van Treuren
SJTAG Chair Emeritus
Posts: 152
Joined: Fri Nov 16, 2007 2:06 pm
Location: VT Enterprises Consulting Services, USA

Additional scope for Use Case paper

Post by Bradford Van Treuren »

Use Case Document
  • For each Use Case:
    • Application field(s)
    • Detailed description
    • Alternative techniques (comparison)
    • Tooling requirements
    • Value proposition
I would like to see more of a format that provides more insights into the thought process behind each use case and when these cases should be used as well as any relations between the different use cases. The points raised by Ian are all necessary, but I think they don't go far enough. I am looking at something like the software community has for design patterns which provide a level of abstraction of concepts that may be applied to specific use case roles. An example format may be found at:
http://hillside.net/patterns/writing/GOFtemplate.htm.

Key take-aways is the scope and purpose, the intent (what does this pattern do?), motivation, applicability (situations the pattern may be applied to), participants, collaborations, and consequences. These are important aspects in understanding more about the use case and how to use the concept effectively.
Last edited by Bradford Van Treuren on Mon Jun 09, 2008 12:13 pm, edited 1 time in total.
Bradford Van Treuren
Distinguished Member of Technical Staff
VT Enterprises Consulting Services
User avatar
Bradford Van Treuren
SJTAG Chair Emeritus
Posts: 152
Joined: Fri Nov 16, 2007 2:06 pm
Location: VT Enterprises Consulting Services, USA

Missing document

Post by Bradford Van Treuren »

I think there is still a missing document listed based on our discussion on June 4. This document is in reference to my statement:
  • My biggest concern is there needs to be some way in tying these topics together and show how all of this together provides and extremely powerful and efficient technology we call SJTAG.
where I feel there needs to be a more detailed document than the overview which will begin to shed light on the value proposition for adding SJTAG to a design. This is sort of a business case model people may start from to introduce the concept to their respective organizations
Bradford Van Treuren
Distinguished Member of Technical Staff
VT Enterprises Consulting Services
User avatar
Jim Webster
SJTAG Member
Posts: 8
Joined: Mon Nov 12, 2007 2:28 pm
Location: Integellus, Bonnie Scotland

Post by Jim Webster »

I'm not really a great fan of several different documents on a single theme, I'd rather see a single document encompassing all. Having said that if we constrained ourselves to an electronic document format with hyperlinks to the separate subjects then this may be the way to go. This could also apply to a CD/DVD type distributed document.

I'd also like to see some form of Rules/Recommendations for each case which discriminate between mandatory conformance and optional conformance. This would be necessary for documents 2, 3 & 4 listed above.

Somewhere in one of the documents/sections we will need some form of description that shows how we propose to link into other system vendor toolsets for SJTAG implementation. Maybe this is what the language document should take responsibility for.

Not sure I agree about the "thought" process being included in documents but certainly there should be something that shows relationships - possibly a case here for a Rule/Recommendation.

We also need to show how in some form or another how we intend initiating SJTAG instructions/tests (not just as architectures).
User avatar
Ian McIntosh
SJTAG Chair
Posts: 504
Joined: Mon Nov 05, 2007 11:49 pm
Location: Leonardo, UK

Post by Ian McIntosh »

Revision 2, incorporating the comments I can remember from today's discussions:
  1. Overview Document
    • Scope of SJTAG
    • Purpose of SJTAG
    • Primary constraints
    • Relationship to other standards
  2. Use Case Document
    • For each Use Case:
      • Application field(s)
      • Detailed description
      • Alternative techniques (comparison)
      • Tooling requirements
      • Value proposition
  3. Hardware Architectures Document
    • External and Embedded architectures
    • Chain topologies
    • Gateways
    • Tooling requirements
    • Mandatory /optional conformance levels (maybe in Overview?)
  4. Languages and Data Formats Document
    • Languages for test flow and control
    • Formats for exchange of device programming operations
    • Formats for exchange of test vectors
    • Formats for exchange of result/diagnostic data
  5. Business Document
    • Synergy arguments
    • ???
Now, some dumb questions:
  1. As an international group, what page size do we expect to use - ISO A4, US Letter, something else?
  2. Do we expect the documents to be used primarily on-screen or printed? Conventional wisdom recommends sans-serif fonts for on-screen and serif fonts for printed material for best readability.
User avatar
Ian McIntosh
SJTAG Chair
Posts: 504
Joined: Mon Nov 05, 2007 11:49 pm
Location: Leonardo, UK

Post by Ian McIntosh »

I've re-uploaded "Volume 1" onto the File Manager, having spent a little time getting it into the kind of shape that I think is starting to look like a reasonable template (I'm sure anyone who is bit more familiar with Writer than I am can do a better job, though :wink: ):

http://files.sjtag.org/wip/white_paper_volume_1.odt

Without the TrajanPro fonts, the heading text defaults back to Times New Roman, which doesn't look that good :( :

http://files.sjtag.org/wip/TrajanPro-Regular.otf
http://files.sjtag.org/wip/TrajanPro-Bold.otf

I've also created a "Context" section at the front of the document, which I think probably ought to appear (maybe in some modified form) in each document. To save downloading the document just to see this, it looks something like this:

1. Context
1.1 About this Document
This document, Volume 1 of 5 volumes, provides an introductory overview of the objectives and defining principles of System-Level JTAG (SJTAG). The document is intended for those readers who are either either new to SJTAG or who only require a basic understanding of the application of SJTAG.
It is assumed, however, that the reader has basic knowledge of the principles of JTAG Boundary Scan Test as described by IEEE 1149.1-2001, “IEEE Standard Test Access Port and Boundary Scan Architecture”.
1.2 Documentation Map
Readers seeking further information on specific topics are directed to the following volumes:
* Volume 2 – Use Cases
- Topic 1
- Topic 2
* Volume 3 – Hardware Architectures
- Topic 1
* Volume 4 – Languages and Data Formats
- Topic 1
* Volume 5 – Business Case
- Topic 1