ITSA Workflow
This commit is contained in:
AzureAD\SylvainDUVERNAY
@@ -0,0 +1,212 @@
|
||||
# Practice Book Generation Guideline
|
||||
|
||||
A reusable specification for producing **ERP "Practice Book" user manuals** for commodity
|
||||
trading clients, derived from two reference documents:
|
||||
|
||||
- *Trading, Middle Office and Derivatives Practice Book* (front-office)
|
||||
- *Shipping Practice Book v2* (operations / back-office)
|
||||
|
||||
Use this guideline as the blueprint when generating an equivalent document for **another
|
||||
customer, another commodity set, or a different workflow** (and, where relevant, a
|
||||
different ERP such as Tryton instead of iRely).
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose of these documents
|
||||
|
||||
A Practice Book is a **"to-be" operational manual**. It is *not* generic vendor software
|
||||
documentation. Its job is to tell a specific client's staff **how their business is to be
|
||||
run inside the configured ERP**, step by step, screen by screen.
|
||||
|
||||
Each book has a clear scope along the trade lifecycle:
|
||||
|
||||
| Book | Scope | Primary audience |
|
||||
|------|-------|-----------------|
|
||||
| **Trade / Middle Office / Derivatives** | Front office: contract capture, pricing, FX fixation, cost budgeting, hedging, broker reconciliation, market exposure, allocation, sales | Traders, Trader Assistants, Market Risk / Derivatives Desk, Finance |
|
||||
| **Shipping / Logistics** | Back office: logistics flows, shipping instructions, load shipment, inventory receipt, vouchers, invoicing, exception handling | Operations, Logistics, Trader Assistants, Finance |
|
||||
|
||||
**Defining characteristics to reproduce:**
|
||||
- Written in the client's own vocabulary and entity names (companies, commodities, ports, banks).
|
||||
- Describes the agreed *target process*, including explicit decisions made during implementation ("we have decided to…", "for simplicity we keep…").
|
||||
- Heavily screenshot-driven: every action is illustrated with an annotated capture of the real configured system.
|
||||
- Honest about gaps: carries open questions, "to be confirmed", and vendor action tags inline.
|
||||
- Organised lifecycle-first (follow the goods/contract from creation to settlement), not feature-first.
|
||||
|
||||
---
|
||||
|
||||
## 2. Document structure (section template)
|
||||
|
||||
Reproduce this skeleton. Sections marked **[shared]** are written once and reused
|
||||
verbatim across every book for the same client.
|
||||
|
||||
```
|
||||
Title page — Client / workflow name
|
||||
Contents — Auto-generated TOC with page numbers
|
||||
|
||||
1. Fundamentals & glossary [shared]
|
||||
- Company / Location and Line of Business
|
||||
- Contract pricing types (e.g. Priced vs Basis)
|
||||
- Contract sequences (multi-line contracts) + any limits agreed
|
||||
- Contracts budget & costs (route / cost-matrix concept)
|
||||
- Contract items (product catalogue philosophy)
|
||||
- Price fixations & hedging (one-liner overview)
|
||||
- Hedging & broker reconciliations (overview)
|
||||
- Allocations & reservations (overview)
|
||||
- Logistics flows (Inbound / Outbound / Drop Ship / Transfer)
|
||||
- Key process names (Shipping Instruction, Load Shipment, Inventory Receipt …)
|
||||
- System-specific term mapping (e.g. "Voucher vs Invoice")
|
||||
|
||||
2. Main subject chapters (lifecycle-ordered)
|
||||
- Each major process = a chapter
|
||||
- Each chapter = intro paragraph + numbered/illustrated steps
|
||||
- Field-reference tables for every data-entry screen
|
||||
|
||||
3. Worked scenarios
|
||||
- One "base scenario" (happy path), fully illustrated end to end
|
||||
- Labelled variants of the base scenario
|
||||
e.g. "Variant-2 (Location: X, Commodity: Y)"
|
||||
- Miscellaneous / exception flows (rejections, claims, transhipment …)
|
||||
- Optionally: "Scenarios that will not happen / for later phases"
|
||||
|
||||
4. Appendix
|
||||
- Overview diagram(s) of end-to-end flow
|
||||
- Cross-reference table (e.g. helpdesk / ticket references)
|
||||
- Footnotes collected from the body
|
||||
```
|
||||
|
||||
> The two reference books deliberately **share section 1 verbatim**. Keep this discipline:
|
||||
> write the fundamentals once per client and paste identically into each book so staff get
|
||||
> the same grounding regardless of which manual they open.
|
||||
|
||||
---
|
||||
|
||||
## 3. Content building blocks (the repeatable units)
|
||||
|
||||
### 3.1 Field-reference table
|
||||
Used for every data-entry screen. The leading number ties each row to a numbered red
|
||||
callout on the adjacent screenshot.
|
||||
|
||||
```
|
||||
| # | Attribute | Description |
|
||||
| - | --------- | ----------- |
|
||||
| 1 | <Field> | What it is, how it is used, who fills it, defaulting rules, worked example |
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Descriptions are **operational**, not just definitional — say *who* enters it, *when*, *why*, and any calculation. Long cells with embedded examples are normal and expected.
|
||||
- Use a `???` / `@vendor: to complete` placeholder for fields not yet finalised rather than omitting the row.
|
||||
- Keep field labels in **bold** when referenced in prose.
|
||||
|
||||
### 3.2 Step sequence
|
||||
Process actions as a bulleted list, in execution order, each meaningful step followed by a
|
||||
screenshot:
|
||||
|
||||
```
|
||||
- Trader clicks **Insert** … [screenshot]
|
||||
- A new window opens; enter the line details [field-reference table]
|
||||
- Click **Save** — system allocates the number (e.g. PC- / SC- prefix)
|
||||
```
|
||||
|
||||
### 3.3 Annotated screenshot
|
||||
The dominant visual. Conventions to reproduce:
|
||||
- Real captures of the *configured* system populated with the client's data.
|
||||
- **Numbered red circular callouts** placed on the fields, matching `#` in the field table.
|
||||
- Placed immediately after the prose/table that describes them, never front-loaded.
|
||||
- For exception flows, before/after captures.
|
||||
|
||||
### 3.4 Notes, examples, open items
|
||||
- **Note / Important Note:** bolded inline callouts for rules, warnings, responsibilities.
|
||||
- *Italic worked examples* with concrete numbers (e.g. freight 4500 USD ÷ 19.2 MT = 234.38 USD/MT).
|
||||
- `[@vendor: …]` inline tags for open questions, bugs, or future enhancements — kept visible in the draft.
|
||||
- Footnotes (`[^n]`) for edge cases that would interrupt the main flow.
|
||||
|
||||
### 3.5 Worked-calculation block
|
||||
For any computed value (freight, finance, insurance, FX), show the **formula then a fully
|
||||
numeric example**:
|
||||
|
||||
```
|
||||
Finance cost = Principal × Rate × Days / 365
|
||||
= 87 848.77 × 2.0% × 60 / 365 = 288.82 USD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Formatting & style conventions
|
||||
|
||||
| Element | Convention |
|
||||
|---------|-----------|
|
||||
| Field / column names | **Bold** |
|
||||
| Buttons / actions | **Bold** (e.g. click **Save**, **Insert**, **Allocate**) |
|
||||
| Worked examples | *Italic*, with real numbers |
|
||||
| System term being defined | **Bold** on first use |
|
||||
| Open questions / vendor actions | `[@vendor: …]` inline, left in the text |
|
||||
| Edge cases | Footnotes |
|
||||
| Process / status names | Capitalised exactly as in the system (In-Transit, Spot, In-Store) |
|
||||
| Headings | H1 = chapter, H2 = process, H3/H4 = sub-process or scenario variant |
|
||||
| Voice | Future/target tense ("we will create…", "the Trader will enter…") |
|
||||
|
||||
Keep the **client's real master data** in every example: company/location names,
|
||||
commodities, ports, incoterms, banks, grades, packaging (e.g. 69 kg bags). This grounding
|
||||
is what makes the book usable and is the single most important thing to localise.
|
||||
|
||||
---
|
||||
|
||||
## 5. How to adapt for a new customer / commodity / workflow
|
||||
|
||||
> **INSTRUCTION — ask before generating.** Before producing a new Practice Book, do **not**
|
||||
> assume answers from the reference documents. First **ask the customer the questions
|
||||
> below and wait for their answers.** Only once the answers are provided should the output
|
||||
> document be generated. Pose the questions grouped as listed; where a question has a small
|
||||
> fixed set of choices, offer them as selectable options, otherwise ask for free text.
|
||||
|
||||
**Questions to ask the customer:**
|
||||
|
||||
1. **Glossary entities.** What are the company/location name(s), the commodity set being
|
||||
traded (e.g. coffee, cocoa, cotton, sugar, grains, iron ore, steel, copper, aluminium,
|
||||
zinc/lead), and the line-of-business dimension? Are there any agreed structural limits
|
||||
(e.g. maximum number of contract sequences/lines)?
|
||||
|
||||
2. **Pricing types.** Which pricing types does the client use — *Priced*, *Basis
|
||||
(differential)*, *formula-priced*, or a combination? Which underlying markets and terms
|
||||
apply (e.g. ICE, LME, SHFE, GAFTA/FOSFA references)?
|
||||
|
||||
3. **Cost matrix & route logic.** What are the real incoterms, typical loading and
|
||||
destination places, and the cost types to budget (e.g. freight, insurance, finance,
|
||||
fumigation, inland, demurrage)? Which costs are auto-calculated vs. manually entered?
|
||||
|
||||
4. **Logistics flows in scope.** Which flows apply — Inbound (origin → warehouse),
|
||||
Outbound (warehouse → buyer), Drop Ship (direct), Transfer (location to location)? Are
|
||||
the goods bagged or bulk (affecting packaging, weights, draft survey, moisture/outturn),
|
||||
and is tolerance/franchise handling required for the commodity family?
|
||||
|
||||
5. **Hedging & FX scope.** What should the book cover — *physical only (no hedging/FX)*,
|
||||
*futures hedging only*, *futures + FX hedging*, or *FX only*? Front-office and physical
|
||||
mechanics must be kept in clearly separate chapters.
|
||||
|
||||
6. **Worked scenarios.** Which dimensions matter for this client's scenario variants
|
||||
(e.g. location, commodity, contract type, packaging, exception type)? Which exception
|
||||
flows must be covered (rejections, claims, transhipment …) and which are out of
|
||||
scope / later phase?
|
||||
|
||||
7. **Screenshots.** Will annotated screenshots be supplied from the client's configured
|
||||
environment, or should the document leave numbered placeholders for them? (Never reuse
|
||||
another client's captures.)
|
||||
|
||||
8. **Target ERP.** Which ERP is the target — Tryton, iRely, or another system? If it
|
||||
differs from the reference (iRely), provide the equivalent term/model mapping (e.g.
|
||||
Tryton models, wizards, states) so iRely-specific terms (Voucher, Sequence, Blotter)
|
||||
can be replaced. The pedagogical structure — fundamentals, field tables, illustrated
|
||||
steps, worked scenarios — is ERP-agnostic and must be preserved regardless.
|
||||
|
||||
---
|
||||
|
||||
## 6. Quality bar (acceptance criteria)
|
||||
|
||||
A generated Practice Book is "done" when:
|
||||
- A new staff member could execute each process end-to-end using only the book.
|
||||
- Every data-entry screen has a matching numbered field table + annotated screenshot.
|
||||
- Every computed figure shows its formula and a numeric worked example.
|
||||
- All examples use the client's real master data.
|
||||
- Open items are visibly tagged, not silently dropped.
|
||||
- The fundamentals chapter is identical across the client's set of books.
|
||||
- Scope boundaries (what is in / out / later phase) are stated explicitly.
|
||||
Reference in New Issue
Block a user