docs: reorganize site structure using Diátaxis framework

- Group hub-documentation into explanation/, how-to/, and reference/ per Diátaxis
- Move ifs-integration.md to new hoist-hub/ category
- Add contributing/ category with Diátaxis framework explainer
- Move tutorial-basics and tutorial-extras under docusaurus-guide/
- Rewrite docs/intro.mdx as site entry point with category navigation
- Update all doc titles to reflect their Diátaxis type
- Add HOIST logo to homepage hero and fix Get Started link
This commit is contained in:
jaime.meza committed 2026-06-18 14:50:15 -05:00
1 parent 2cfb6f5ef7
commit b9a194f7c5
44 files changed
+200 -63

No files matched your search

@@ -0,0 +1,8 @@
{
"label": "Reference",
"position": 3,
"link": {
"type": "generated-index",
"description": "Templates, field definitions, and structural standards for every section of a HUB spec."
}
}
@@ -0,0 +1,71 @@
---
sidebar_position: 3
title: Approvals & Deliverables Template
---
# Approvals & Deliverables
## Approvals
This section is mandatory and must be completed in accordance with the established process for every specification, as it captures the initial approval. The Hoist Business Analyst is responsible for obtaining this sign-off. Any approvals for subsequent changes will be recorded in the Change Log section.
### Functional Design Definition Approved
| Approver | Date Approved | Artifact | Change No. |
|----------|--------------|----------|------------|
| | | | |
### Technical Design & Estimate Approved
The TSM is responsible for getting this sign-off.
| Approver | Date Approved | Artifact | Change No. |
|----------|--------------|----------|------------|
| | | | |
---
## Deliverables
This section, owned by the developer, documents the final deliverables of the task. It must specify:
- The components included in the delivery
- The delivery format (e.g., Delivery Build, Application Configuration Package (ACP), or Manual Deployment with instructions)
- For ACP deliveries: the name of the ACP
- For deliveries uploaded to DevOps (IFS Cloud): the specific folder within the Build Home structure where the files are located
---
## Delimitations & Dependencies
The configurations in this specification have been configured as documented. Requests for changes in the configuration necessary to fulfil (or prepare for future fulfilment of) any requirements not explicitly described in the business requirements specification will be considered outside the scope of this configuration.
The following are excluded from this specification:
- Translations other than stated under the translations chapter
- Changes or extensions on Online Help (F1 Help), e-learning material, or process models
Document what is **NOT** covered by this specification, including functionality that will not be implemented. If you refer to external documents, make sure to include them either in the Appendices or in the Foundation for Functional Specification section.
---
## Go-Live Information / Upgrade Issues
Enter vital go-live information if appropriate, e.g.:
- Basic data setup
- Scheduled tasks
- Permission Sets
- Whether upgrade scripts are required or manual data updates in IFS Applications are needed when the configuration is installed
*Delete this section if not applicable.*
---
## Performance Considerations
This section is owned by the developer. Provide guidance on data volumes for the main tables. Does not need to be precise but should give an order of magnitude.
**Example:** The volume of data within the new functions is unlikely to be high. Typically, there could be several hundred X records and up to 10,000 Y entries each. There are no expected issues with high volume processing or large tables to be considered in the design and coding.
*Delete this section if not applicable.*
@@ -0,0 +1,66 @@
---
sidebar_position: 1
title: Business Requirements Definition
---
# Business Requirements Definition
The HOIST Business Analyst is responsible for drafting this section, outlining the solution scope in collaboration with the customer. This is the conceptual overview of what the HUB feature will accomplish. The customer is responsible for reviewing and approving the content to ensure it accurately reflects the original requirements.
During the specification sign-off process, the customer evaluates the documented scope and provides feedback as needed to ensure 100% alignment with business needs.
---
## Business Value
Describe the benefits and the business value — **not a proposed solution** — that can be achieved by improved system support. It is beneficial for the overall understanding if the benefits of the changed system support can be stated clearly.
---
## Current Process / Workflow
Describe the GAP in the IFS workflow or functionality that causes the need for this HUB feature.
### In IFS
Describe how it works in IFS:
- IFS Navigation (e.g., Sales / Quotation / Sales Quotation)
- Reference an existing Work Instruction if available
- If no WI exists, provide a brief description of how to navigate in IFS
- Include IFS screenshots if needed
---
## Desired Outcomes & Desired Process / Workflow
Describe the desired behavior from the system and the resulting process/workflow.
---
## Business Requirements Details
This section focuses exclusively on detailing the business requirements. It should **not** include functional or technical requirements, as those will be addressed in subsequent sections.
The table below itemizes each requirement point in detail:
| Req. # | Description | Business Owner | Related Req. |
|--------|-------------|----------------|--------------|
| 1 | To associate a part master record with a customer | | 1 |
| 2 | To run a report returning all parts belonging to a specific customer | | 1 |
---
## References, Sources, and Relations to Other Customizations
To support the requirements outlined in this specification, you may reference relevant documents, examples, or resources available on the project SharePoint site. Please ensure these references directly relate to the content.
:::caution
If this specification was developed using a preliminary document from the customer, do **not** attach that document here — it may cause confusion.
:::
| Ref. # | Title | Description | Type | Related Req. |
|--------|-------|-------------|------|--------------|
| 1 | | Document explaining the business requirements | document | |
| 2 | | Report layout document | layout | |
| 3 | CRIM 123 | There is a customization — here is the spec | spec | |
@@ -0,0 +1,39 @@
---
sidebar_position: 4
title: Change Log
---
# Change Log
:::danger
Very Important
This section is **exclusively** for recording all subsequent changes to the delivered HUB feature, encompassing change requests, requirement misunderstandings, and bug fixes.
:::
Each change — whether a change request, requirement misunderstanding, or bug fix — must be documented as a new entry with the same level of detail as the original Sub-Function section of the specification. The **original Sub-Function section must remain unchanged** to ensure the initial requirements remain visible.
Every entry should provide:
- A concise, high-level explanation of the reason for the modification
- The affected design sections, using clear tags or markers to highlight changes in lengthy specifications
- An explicit indication of whether the entry addresses a **bug fix**, a **requirement misunderstanding**, or a **customer-requested change**
---
## Document Revision History
| Revision | Date | Author | Remarks |
|----------|------|--------|---------|
| 1 | 2026-03-17 | Najib El-Husseini | Initial Draft |
---
## Detailed Description — Change #1
Take the required sections from the Business Requirements Definition, Functional Design Definition, and Technical Design Definition to properly document the full change to this HUB feature. Include new test plans for the updated functionality.
---
## Detailed Description — Change #n
Take the required sections from the Business Requirements Definition, Functional Design Definition, and Technical Design Definition to properly document the full change to this HUB feature. Include new test plans for the updated functionality.
@@ -0,0 +1,56 @@
---
sidebar_position: 2
title: Estimates Template
---
# Estimates
The PM is responsible for the number of hours estimated for this HUB feature. The technical and functional resources will tell the PM their individual estimates and the PM will enter that combined number here.
This estimate includes:
- The time required to detail the requirements and functional design in this document
- The time required to hand over and discuss the requirements to the developer
- The time required to detail the technical design in this document
- The time required by the HOIST developer to develop the solution and delivery artifacts
- The time required by the HOIST developer to perform technical testing
- The time required by the HOIST business analyst to perform functional testing
- The time required by the HOIST business analyst to perform testing with the client
---
## T-Shirt Estimate
This section is used to specify a rough estimate for the development of the features specified in this HUB Spec. This estimate is given before any detailed business requirements have been captured and will be based on the QTY per type of HUB feature (New Module, Page, Field, Feature), but will not reflect details regarding how difficult or simple the implementation will be.
| Size | HUB Type (Example) | Hours |
|------|--------------------|-------|
| XS | Extra Small | 4 |
| S | Small | 8 |
| M | Medium | 16 |
| L | Large | 40 |
| XL | Extra Large | 80 |
| EPIC | EPIC | 100+ |
### HUB T-Shirt Estimates
| HUB # | Description | Size | Total Hours |
|-------|-------------|------|-------------|
| 1 | Sales Quotation | Epic | 24 |
---
## Detailed Estimate
| HUB Obj # | Description | Estimator(s) | Estimate Type | Estimated Hours |
|-----------|-------------|-------------|---------------|-----------------|
| | Detail Requirements | | Func. | |
| | Func. / Tech. Collab. | | Func. / Tech. | |
| | Detail Requirements | | Tech. | |
| | Development | | Tech. | |
| | Testing | | Tech. | |
| | Testing | | Func. | |
| | Delivery | | Tech. | |
| | Testing | | Func. | |
| | Client Testing | | Func. | |
| **TOTAL:** | | | | |
@@ -0,0 +1,76 @@
---
sidebar_position: 2
title: Functional Design Definition
---
# Functional Design Definition
This section, crafted by the Hoist Business Analyst in close partnership with the customer, provides a comprehensive guide to the solution. It outlines how the HUB feature will address the requirements specified in the Business Requirements section, ensuring all aspects are thoroughly covered.
To support developers — especially those unfamiliar with the relevant IFS functionality — this section includes:
- **Process Flow Diagram** done in Visio (e.g., Create Quote to Convert to Order). Start by reviewing the master flow diagram: *Mobile and IFS Flow on Hoist Hub* in SharePoint. Diagram needs to fit in an 8.5 x 11 Portrait format.
- **Screens** — description, mock-ups, fields, buttons and actions, workflow
- **Approvals** — approval logic if needed
The customer will review and approve this section during the sign-off process to confirm it aligns with their expectations.
---
## Screens
For each screen, document the following:
### Screen Description
Describe the purpose of the screen and the general use of it.
### Screen Mock-Ups
Visual representations of the user interface. Initially display wireframes done in Visio or Balsamiq. As screens are developed, take snapshots and annotate changes with Snagit.
### Fields
Fields in the table must be in the order they appear on the screen.
| Name | Characteristics | Notes |
|------|----------------|-------|
| Quotation No | View Only | Populated on Save to IFS |
| Customer | Dropdown, Mandatory | Dropdown from IFS Customers |
| Delivery Date | Enterable, Mandatory, Date Field | Date Picker |
**Characteristics legend:**
- View Only
- Enterable
- Mandatory / Not Mandatory
- Dollar, Date, Text, Dropdown
### Buttons and Actions
| Name | When Active | On Click Actions |
|------|-------------|-----------------|
| Save | Always | Save Quote Header to IFS; Return the Quotation No; Save Quote record to HUB |
### Workflow
Describe the workflow logic if needed:
- Sequential
- Parallel Any
- Parallel All
### Approvals
Describe the approval logic if needed.
---
## Permissions & Security
Use this section to define which HUB Profiles have which Permissions.
| HUB Profile | HUB Permissions | Notes |
|-------------|----------------|-------|
| External User | Can Create Quotes on HUB | |
| External User | Can Delete Quotes on HUB | |
| External User | Can Update Quotes on HUB | |
@@ -0,0 +1,129 @@
---
sidebar_position: 3
title: Technical Design Definition
---
# Technical Design Definition
This section is owned by the developer and should be updated with the solution as it was developed. The Hoist Business Analyst will be consulted as needed.
:::warning[Mandatory]
This section is **mandatory** for all desired HUB Specs. All unused sections must be deleted.
:::
---
## HUB Tables / Columns Mapping to IFS
List of HUB fields and their mapping into IFS fields:
| HUB Screen / Tab | HUB Label | HUB Table / Field Name | IFS Screen / Tab | IFS Label | IFS View / Field Name |
|------------------|-----------|------------------------|------------------|-----------|----------------------|
| Quote / Header | Quotation No | Quote / Quote_No | Sales Quotation / Header | Quotation No | Order_Quotation / Quotation_no |
---
## HUB to IFS API Calls
List of HUB Events that call IFS APIs:
| HUB Screen / Tab | HUB Button / Event | IFS API | Purpose |
|------------------|-------------------|---------|---------|
| Quote / Header | Save Button | Create_Quotation | To send the Quotation entered on HUB into IFS. API will return the Quotation No for saving on HUB |
---
## Report Layout
This section applies to both IFS Report Designer and Crystal Reports. IFS encourages customers to do their own layout modifications (as long as they're using Report Designer layouts).
Include an illustration or picture of the existing report or a data drawing of how it should look. Since a report can have multiple layouts, create a subsection within this section for each layout to be modified.
### `[REPORT_ID]` – `[REPORT_TITLE]`
#### Layout
`[layout_file_name.rdl]`
#### Description of Report Layout Properties
Document the following aspects where an exact match is required (e.g., for legal purposes, automatic processing):
- Paper size and orientation
- Font (type, size, bold/italic/underline, etc.)
- Position (e.g., 2cm from left margin, directly below line x)
- Text alignment (left, right, centered, top, bottom)
- Text wrapping or truncating
- Date format
- Number format (thousands and decimal separator, decimal places)
- Conditional displaying
- Graphics (e.g., company logo)
- Calculations/formulas
- Headers and footers
- Page breaks
- Special considerations for First Page, Repeat Section, and Last Page
- Barcodes
#### Mockup of the Report Layout
Include a screenshot of a mockup of the intended report layout.
---
## Scheduled Task
### Purpose
Describe the purpose/need of the Scheduled Task.
### Description
Describe the Scheduled Task.
### Scheduled Task Setup
| Schedule name | Task Name | Schedule | Advanced |
|---------------|-----------|----------|----------|
| | Select from LOV | Daily / Weekly / Monthly / Scheduled / Interval / Custom + Time | e.g., language code or start and end date |
### Parameters
Define any special parameters to be used by the scheduled task.
---
## Workflow
### Workflow Purpose
Describe the background/purpose for the Workflow.
### Workflow Description
Describe the objective(s) of the Workflow. Is it principally about Process Enrichment, User Interaction, or Data Validation?
### Workflow Key
Format should be CamelCase (e.g., `WorkTaskZoneCharge`).
### Workflow Description / Outcomes
Describe in non-technical terms what the Workflow should do. This can be a bulleted list or a flow chart if requirements are complex.
**Example:**
> When a Service Work Task is Released, the workflow should:
> - IF Site = 999 → do nothing
> - ELSE → look up the service object on the task, then look up the service location for that object, then fetch the Location Type from the Scheduling tab on the Location; this location type ID will match a Non-Inventory Sales Part number; the workflow will add a Work Task Sales Line based on this Sales Part number with quantity 1; standard pricing rules apply to the sales line.
### Workflow Activation
Describe under what situations the Workflow should be triggered. Also indicate scenarios under which it should **not** be triggered.
**Projection Reactions vs. Custom Events:**
- Use **Projection Reactions** when the workflow should be triggered by a change on a specific page but not on other pages for the same database table.
- Use **Custom Events** when the workflow should be triggered by database changes at a table level, regardless of which IFS Cloud Web page the user made the change on.
**Capturing different scenarios:**
Describe all scenarios that should lead to the workflow being triggered. Consider all creation paths: manual creation, adding to an existing request, from the Mobile Work Order app, from a Recurring Service Program (manually or by scheduled generation), etc.
@@ -0,0 +1,44 @@
---
sidebar_position: 1
title: Test Plan Template
---
# Test Plan
## Technical & Unit Testing
Developers are required to thoroughly test HUB functionality by evaluating parameters such as null values, edge cases, and all potentially valid inputs against the technical specifications and requirements. Testing must confirm that no error messages are generated. Additionally, developers should perform regression testing between version changes to ensure that all existing HUB functionality remains correct and unaffected.
| Business Req # | HUB Obj # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|----------------|-----------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
| | | | | | | | | | |
---
## Business Test Plan
This section details the testing procedures to verify that the HUB spec fulfills the business requirements outlined in the specification. Test plans must directly align with these requirements to confirm their successful implementation.
Testing instructions should be:
- Clear and step-by-step
- Accessible to individuals unfamiliar with the solution
- Include specific basic data (sample inputs or datasets) for reliable and repeatable outcomes
Collaboration between the HOIST Business Analyst and the customer is essential to develop accurate and mutually agreed-upon test plans.
| Business Req # | Test # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|----------------|--------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
| | | | | | | | | | |
---
## Client / User Testing
This section is designed for use by the customer during the customer testing phase. The table in this section must align with the table in the Functional Results section above.
Successful testing of the HUB feature confirms that it has been developed and delivered as specified. Any changes or additional requirements should be documented in the Change Log section.
| Business Req # | Test # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|----------------|--------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
| | | | | | | | | | |