search

ArrowheadFramework / ahfc-broker-quorum-jsonrpc-ws

AHF broker system (Quorum/JSON-RPC 2.0/Web Service).
2 stars 1 forks source link

Writing the Broker Arrowhead Documentation #1

Closed emanuelpalm closed 6 years ago

emanuelpalm commented 6 years ago

Objectives

The following are the documentation guidelines relevant to the current specification efforts:

  1. System Description (SysD)
  2. Semantics Description (SD)
  3. Interface Design Description (IDD)

Examples of those documents written by myself can be found here.

We need to write documentation for the Broker system on this form. The SysD should give the bigger picture of the Broker system. The SD document should describe the services and data objects exposed by the Broker in abstract terms (i.e., without associating the Broker with any particular protocols or technologies). Lastly, the IDD document should describe the same things as the SD document, but in terms of concrete protocols and technologies.

Plan

My suggestion is that we write the documentation directly in this repository, in the form of Markdown and /** TypeScript documentation comments (similar to javadoc) */. When we start nearing completion, I can aggregate all the documentation into the Arrowhead Standard PDFs, which will be sent around for reviewing before being ratified. As the line between the SD and IDD documents becomes rather thin here, as we are working with concrete TypeScript/JavaScript definitions, I propose we assume those to be one and the same thing in this repository.

Here are the locations of all relevant documents in this repository:

/source/main/arrowhead

emanuelpalm commented 6 years ago

@NoahWinneberger

emanuelpalm commented 6 years ago

Due to a request from Olov, I changed the names of the frontend and backend folders to arrowhead and quorum, respectively. Also, I moved the old arrowhead folder into the new arrowhead folder, and renamed it spec. I was probably a bit too quick to choose the frontend/backend folder names. Those terms carry too much association.

While doing all of this, I added README.md files to more of the source code folders. I'm going to try and refine them in the future.

@NoahWinneberger I hope the new names make more sense than the old ones. ;)

emanuelpalm commented 6 years ago

This issue is no longer relevant, as the documentation effort has shifted over to the official Arrowhead repository.

https://forge.soa4d.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=arrowhead-f/arrowhead-f.git;a=tree;f=3_Core+Systems/2_Support+Core+Systems/11_Broker+system/Documentation;h=27286d092661eb08dec941d6eb7afa256097f2b4;hb=HEAD