Skip to main content

Hackathon 2022-05-10

Plan​

The golden commandment of technical writing is “thou shalt not assume”. You might think you’re being obvious, but you have to be aware of the knowledge level your audience is at.

Teams​

XRAY team - [@ime_tima]​

@jovana @dusko @ranko @milan

Plusius team - [@ime_tima]​

@suzana @mmatic @mpasic @dragana

Tango team - [@ime_tima]​

@natasa @nevena @marko @bojan

Help​

@milica @mirko

Goals​

What do your users want to achieve? You should know what a user can accomplish once they’re done with the documentation. This way, you can set learning goals that actually help users achieve their main goal.

General goals​

  • increase the level of internal documentation for better knowledge share, easier new employees traning, less questions around, fewer errors, increasing efficiency etc.
  • bring closer the products we make to the broather audience - whether it's about developers, sales, marketing or business people
  • terminology - cover the section addressing terminology and it's meaning like KYC - know your customer or GraphQL, REST, SDK, - so we can reference to this index in the content

Product goals​

Products (XRAY, Plusius, Tango)

  • explain the purpose of the product
  • explain the features / posibilities of the product
  • explain the ways of using the product (interface / API) and how to start / install
  • explain the products / subscription models
  • detailed API description (objects / mutations / queries / REST) and extending current api generated objects (additional description for every type / endpoint)
  • tutorials for API integration
  • Use cases - one or two examples (tutorials and usecases could be the one thing)
  • user manual for the interface

Learning objectives​

Your learning objectives support the user’s goal. Objectives are an internal tool that helps your writer collect the information a user needs to become proficient in their knowledge and achieve their goals.

Our learning objectives​

  • learn how to integrate with XRAY/Plusius

An outline​

What topics and subtopics will you be covering in your technical documentation? Think of this as a table of contents and try to list out every major section and subsection you think you’ll need.

XRAY table of contents​

Plusius table of contents​

Audience​

Keep your readers top of mind at all times. This will ensure you write something that people actually want to read.

Docs consumers​

Receivables​

What information do you already have on hand? What information do you need? For example, maybe you need to interview a PM or developer to get more information.

Developers, developers, developers...​

Deliverables​

When is it due and what format will it be in? Technical documentation is as much about structure and delivery as it is content. And knowing how the content will be presented before you start will tell you what you need and where to put your efforts.

We are expecting to have full functional standalone documentation - where developer could read documentation, get information and intergrate.

Prize​

Supplies! <3

Tech stack​

Document management tool​

https://docusaurus.io/ and plugins...

Azure DevOps project​

https://dev.azure.com/INVENIT2/InvenitSolutions

Deployment​

Azure Static Services - including CI/CD on Azure DevOps

Tasks​

Inline GraphQL Docs​

Queries and mutations description is great source of information for API users and we should make sure all objects should have description.

GraphQL Playground / Banana Cake Pop / GraphiQL extension​

Check with these to extend it's main capability - in a way of making it easier to put examples and test queries / mutations

Mermaid​

Understand how it works and how to create basic graphs. More info: https://mermaid-js.github.io/mermaid/#/

Existing resources​

XRAY​

Currently supported checks on XRAY: Example banner

Business Adverse Media (+PEP +SL)

Business Adverse Media with bundled Sanctions list and PEP check

Business sanctions list

Sanction check against organizations

Business sanctions (+PEP)

Business sanctions with bundled PEP check

Personal Adverse Media (+PEP +SL)

Personal Adverse Media with bundled Sanctions list and PEP check

Personal sanctions (+PEP)

Sanctions list against individuals with bundled PEP check

Plusius​

XRAY sequence diagram as a use case