Skip to content

Functional Demo & Technology Preview

Goals

  • Replace the existing Ross-Tech WIKI as the primary knowledge base for customers
  • Define a future proof scheme for information and files to:
    • Allow linking knowledge base articles/pages from inside VCDS & VCDS-Mobile, forums as well as other external sites (via unique identifiers)
    • Allow linking knowledge base articles/pages from saved/printed Auto-Scan's
    • Local/offline previews and changes before deploying to the live system
    • Add full versioning and a review process for new content via a markdown based approach
    • Prepare for special use cases like a searchable offline version
  • Modern look and feel by using latest web technology (HTML & CSS)
    • Fully responsive layout for every screen size and device
      • True mobile device support
  • Include the new knowledge base into the VCDS
    • Add KB/WIKI entries to the Auto-Scan results
  • Include the new knowledge base into the VCDS-Mobile app to:
    • Add benefits for non-HEX-NET users
    • Add a second screen for information and additional details via the users mobile devices
  • Minimize server maintenance efforts and improve performance by switching from a database driven content management system to a static site generator
  • Improve server side security by entirely removing unnecessary attack vectors (i.e. MySQL, PHP, MediaWiki etc.)
  • Future multi-language support and/or learning model based answers to customer questions
    • Limited with mkdocs-material(-insiders) but foreseeably simpler with Zensical
  • Full GDPR compliance by no longer using any cookies or externally hosted content & technologies (fonts, analytics etc.)

Technology

Switching from MediaWiki as a platform, primarily based on PHP and MySQL will simplify future updates and maintenance efforts and disconnect content from the used technology/framework, allowing for more use cases and alternative integration of the data (for example directly into VCDS or VCDS-Mobile) down the road.

Content (text, images etc.) will be maintained in a standard git repository, allowing for additions & changes to be properly reviewed in order to ensure quality and consistency across all content.

An integrated issue tracker as part of the git repository allows requests & suggestions from select non-editors and non-maintainers, while allowing editors and maintainers to follow up and resolve these entries. With the possibility of more focused planning and specific milestones, the project can achieve a better overall consistency and quaility.

Fully automated deployment to the live system via GitHub Actions. Once a main branch is pushed the build/deployment process/action will automatically start.

Features

Abbreviations & Glossary

A site wide glossary file containing abbreviations ensures that standard terms and typical VAG abbreviations like SFD or ODIS are automatically highlighted/hinted. This information is auto-appended to all pages w/o user input.

Glossary File Source (includes\abbreviations.md)
*[DTC]: Diagnostic Trouble Code(s)
*[ODIS]: Offboard Diagnostic Information System (Original Audi/VW Factory Diagnostic Tool)
*[PVD]: Protection of Vehicle Diagnostics (aka. SFD)
*[SFD]: Schutz der Fahrzeugdiagnose (Token based Unlock / Protection of Vehicle Diagnostics (PVD))
*[SFD2]: Schutz der Fahrzeugdiagnose (End-to-End Encryption)
*[SVM]: Software Version Management

The functionality also allows for multiple source files, from which the system will automatically gather the individual lines needed. This could be applied in a component locator related list which would translate G85 as well (Hint@Jef).

Admonitions

While we have similar functions like Admonitions in the past, these are much easier to add and can also be sourced from external files via Snippets. With several different types and functionalities like modified titles or even removed titles, collapsible but collapsed as well as collapsible and initially expanded.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Tip

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Example

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Danger: DO NOT MESS WITH BYTE 18!!!

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

They can also be used nested into each other as well as in combination with other functions like code blocks, images, tables and more.

Outer Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Inner Warning

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Example

Auto-Scan, Address 08 (Excerpt)
    Address 08: Auto HVAC (J979)
    Part No SW: 1EE 907 007 B    HW: 1EE 907 007 B
    Component: Climatronic   H01 0146 
    Coding: 60202224A010120001100010110001102000103111101101000000000000
    ASAM Dataset: EV_ACClimaBHBE3ADV 002032
    VCID: 343943BEEEB8FC1A4F3-8060-R SFD+SFD2

Annotations

Where needed, we can now use include additional information by using Annotations. This reduces the typical clutter on a single page while still providing additional detailes to the user.

A typical annotation displays as a clickable icon. (1)

  1. 🙋‍♂️ Once clicked a tooltip with code, formatted text, images, ... (basically anything that can be expressed in Markdown) will pop up.

Badges

Badges can be used for different purposes ranging from extending circumstantial information about a specific vehicle system/control module to enhancing our manual with additional information like displaying a minumum version. Here are a few examples of badges already defined and in use.

To see these in action, check our the Manual > Auto-Scan and the ID. Buzz model page.

Caching

A build time Caching functionality ensures that updates are sped up as much as possible and incremental uploads speed up the deployment onto the public server. This happens in the background and is already set up to ensure a quick deployment.

Code Blocks & Highlighting

The new Code Block functionality adds several different new functions like the ability to highlight line ranges, individual lines and even specific parts of a typical code block.

Auto-Scan, Address 08 (Excerpt)
   Address 08: Auto HVAC (J979)
   Part No SW: 1EE 907 007 B    HW: 1EE 907 007 B
   Component: Climatronic   H01 0146 
   Coding: 60202224A010120001100010110001102000103111101101000000000000
   ASAM Dataset: EV_ACClimaBHBE3ADV 002032
   VCID: 343943BEEEB8FC1A4F3-8060-R SFD+SFD2

Data Tables

Opposite to our previous MediaWiki, the Data Tables here are much more editor friendly and allow easy integration of icons and other content as well. In addition an Import Module allows to have data in classic CSV files (or even XLSX) instead, making future changes and updates even easier.

Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource
Source: Data table, columns aligned to left
| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource
Source: Data table, columns centered
| Method      | Description                          |
| :---------: | :----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource
Source: Data table, columns aligned to right
| Method      | Description                          |
| ----------: | -----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Sortable tables exists as well, though we may not have a use case for these (yet).

Diagrams

We now have the ability to add diagrams which are generated via simple text/syntax.

graph LR
  A[Customer Question] --> B{Debugs available?};
  B -->|Yes | C[Contact Eric];
  C --> D[Eric does Magic!];
  B ---->|No| E[Blame Santos!];
  E --> B;
Flow Chart Source
``` mermaid
graph LR
  A[Customer Question] --> B{Debugs available?};
  B -->|Yes | C[Contact Eric];
  C --> D[Eric does Magic!];
  B ---->|No| E[Blame Santos!];
  E --> B;
```

Footnotes

Footnotes are kind of self explaing, right?1 While normal footnotes are always displayed in the actual footer and you can reach them by clicking on the superscripted number, mkdocs-material also supports displaying them as tooltips when you hover over them with your mouse.2

Instant Previews

Instant Previews are a really cool feature that will display selected content from a linked page. This can either be a general information like the header and the content from the first section or any sub-section already defined on the target page.

(Hover over the links above for a demo.)

Privacy

The Privacy Plugin downloads external resources like Google Fonts or included Emojis and Icons during build time. All references in our pages and documents will then reference the local copies instead. This ensures not just a snappier browser experience (due to no longer needing to download data from multiple servers) but also makes the new site fully GDPR complient without the need to use cookie banners/permissions.

The built-in Search based on lunr.js is extremely powerful and fast. It works fully independant and even offline across the entire site. It works live when typing, starting with the first typed character and can be customized to be language specific or to obey certain search parameters. The search results can be shared and will highlight once the destination page is opened.

Via metadata each page can also be modified to rank individual pages up/down to increase/decrease their prioritization in the search results. When needed pages can also be excluded entirely.

Try it out!

Test the search function in this demo/preview by using the search field on the top right of the header. To see how a shared result works, click here.

Snippets

Especially for our use case, Snippets are a really powerful feature. In the existing MediaWiki we have often linked to individual sub-pages from multiple sources (like the individual model pages) but the actual content was always on the specific sub-page and had to be managed there.

Snippets now allow us to use individual source files for parts of a single page (technically we can even define lines, ranges etc. to be used from the source file and not the enture file) and then include the content in the new page.

Consider the old Steering Wheel Control Module Versions page, which had 3-4 different content pages all in one but the correlating individual pages for 1K/3C/5K Steering Wheel Control Modules had to have a link instead of the actual content (so users had to active change pages to see the detailed info).

The Battery Replacement page is a similar case, multiple different sub-sections referring to different models/modules requiring the user (who came from a specific model page) to now choose which part/section applies to their case. With Snippets we can include the matching info directly into the model/module specific page while not having multiple source files to maintain/update.

Social Cards

Social cards will be used when sharing links to the knowedleg base via social media, messenger apps and other forms of communication. They contain a custom design and base information about the page linked to. These details are automatically generated for each page and ensure putting our brand and content into the right place to be seen.

Tabs

Remember our code block and highlight example earlier? Well, these can even be nested inside tabs.

Auto-Scan, Address 09 (Excerpt)
    Address 09: Cent. Elect. (J519)
    Part No SW: 1EE 937 089 D    HW: 1EE 937 089
    Component: SAM_H         H08 0530
    ASAM Dataset: EV_SAMVW31x 005001
    VCID: 43DB1062BB164BA2C69-8016 SFD
Auto-Scan, Address 06 (Excerpt)
    Address 06: Seat Mem. Pass (J521)
    Part No SW: 1N3 959 760 H    HW: 1N3 959 760 H
    Component: MEM-BFS       011 0571
    Coding: 0118BA4000012A008803010101010000000000000000000000000000211000
    ASAM Dataset: EV_SCMPasseSideCONTIAU736 006013
    VCID: 3E2D6196D0F4264AA97-806A-R
Auto-Scan, Address 08 (Excerpt)
    Address 08: Auto HVAC (J979)
    Part No SW: 1EE 907 007 B    HW: 1EE 907 007 B
    Component: Climatronic   H01 0146 
    Coding: 60202224A010120001100010110001102000103111101101000000000000
    ASAM Dataset: EV_ACClimaBHBE3ADV 002032
    VCID: 343943BEEEB8FC1A4F3-8060-R SFD+SFD2

Tags

Tags should be self explaining, we already use categories in our MediaWiki. These tags will do a similar job and at a later date allow for more fine grained search and other improvements.

Roadmap

Knowledge Base (Todo)

  • Automate the content migration from existing MediaWiki
    • Different approaches available, from writing an own converter to using existing technology like pandoc or markitdown
    • Define a review process for the initial migration
    • Migrate content
  • Define templates / best practice examples for each content type (DTC's, Functions etc.)
  • Ensure link compatibility to original MediaWiki
    • Automated verification via Sitemap.xml of the original/old MediaWiki
  • Design for the new framework (reuse new design of rt.de)
    • Add special designs for social media cards for different content types

Knowledge Base (Wishlist)

  • Consider anti (AI) bot scraping measures for the new site
  • Consider analytics for a better understanding which pages, search terms and information is most commonly or rarely used, referred to and/or searched.
    • Add content based on analytics results about missing pages/content.
    • Check for unwanted referrers indicating clone seller/manufacturers and/or other unauthorized uses.
  • VIN based Vehicle Identification to allow users to locate the proper model/information w/o w/o actual diagnostic details being available.

VCDS Integration

Knowledge Base Identifiers

We constantly receive customer feedback via mail, forum posts, telephone interactions as well as live trainings and a constant issue is a disconnect between VCDS itself and finding additional information beyond what's shown at and by the vehicle. Most often this applies to specific control modules/systems a user is working right at that moment.

, a topic we have been discussing internally since 2008 (FS#17) is how to connect VCDS with external/online resources. In 2015 I specified a knowledge base identifier and started implementing it in 2017 as W,VCRNNXXXX for our label files. The intent was to make the identifier independant from unreliable label file names and allow language neutral links to be opened/called by VCDS. With this identifier being read from a label file (during an Auto-Scan or when accessing a control module), VCDS can connect that to a typical base URL (from it's resources) and request a browser to open that specific URL. This will lead the user directly to a page associated with the specific system they are working on while being live with the vehicle.

  • i.e. https://kb.ross-tech.com/system/VCRNNXXXX
  • i.e. https://kb.ross-tech.com/procedure/VCRPXXXXX

If we wanted to go all out, VCDS could also generate a QR Code that could be scanned with a mobile device which then opens the correlating page on said secondary device/screen.

Adding KB/VCR Identifiers to the Auto-Scan

While having live access to systems is one thing, finding the proper resources after having worked on a car or while preparing to work on it, is a different story. To help customers finding the right information, the same identifier can be added to the Auto-Scan result. Customers and support will then be able to easily locate that in the knowledge base by using the search function.

Auto-Scan, Address 16 (Excerpt)
    Address 16: Steering wheel        Labels: 1K0-953-549-MY8.lbl
        Part No SW: 1K0 953 549 BN    HW: 1K0 953 549 BN
        Component: J0527           051 0101  
        Coding: 0000042
        Shop #: WSC 31414 790 00001
        VCID: 7F5068B7DBFEA512E69-802A KBID: VCR160099

Historically all WIKI related DTC links did not follow a strict naming convention. It was left to the author of each individual entry/page to make sure the proper name was chose. With this Knowledge Base we can not just start from scratch but make use of an extremely simple approach. We should be able to cover most DTCs by using the old 5-digit VAG code as well as the newer OBD2/EOBD codes.

  • https://kb.ross-tech.com/dtc/00003
  • https://kb.ross-tech.com/dtc/P0016

This general concept was proposed in 2009 (FS#202) and could be implemted by a right-click context menu entry in both the Auto-Scan dialog as well as the fault code dialog. We have had good experience with this feature in the VCDS Suite already.

VCDS-Mobile App Integration

While the VCDS-Mobile app currently targets HEX-NET users only, it still gets downloaded by many others who then have a frustrating experience and leave poor reviews. While this is an issue by design and we can't make other interface types compatible, we can extend the use cases for the VCDS-Mobile app.

The knowledge base is designed as a fully responsive website, which can easily be integrated into the VCDS-Mobile app. This will ensure non-HEX-NET users have diagnostic information at their finger tips when using their mobile device as a secondary screen while working on vehicles.

Structure & Navigation

  • Manual (Interactive)
    • (Function Chart)
    • VCDS
    • VCDS-Lite
  • Diagnostic Procedures
    • Brands
      • Models
        • Control Modules
          • Control Module Functions
    • Engines
    • Transmissions
    • Common Procedures
    • Retrofits
  • Fault Codes
  • Information
    • Official Factory Repair Information
    • Immobilizer
    • Component Protection
    • Schutz der Fahrzeugdiagnose (SFD)
    • Common Acronyms

Naming Convention

File Naming

Identifier
Prefix		 Meaning Description
VCM% VCDS Manual Manual related Content
VCR% VCDS Resources (All) Diagnostic related Content
VCRNN%
VCRNNNN%		 VCDS Resource: Address NN
VCDS Resource: Address NNNN		 Control Module related Content
VCRR% VCDS Resource: Retrofits Retrofits related Content

File & Folder Structure

  • Diagnostic Procedures
    • /procedures/
    • VCRPXXXX
    • VCRPXXXX-SP1 (Special Notes/Information/Functions 1)_
    • VCRPXXXX-SP2 (Special Notes/Information/Functions 2)_
    • VCRPXXXX-SPX (Special Notes/Information/Functions X)_
  • Brands
    • /%brandname%/
    • /audi/
    • /bentley/
    • /ford/
    • /ktm/
    • /lamborghini/
    • /misc/ (Others)
    • /seat/ (Seat & Cupra)
    • /skoda/
    • /volkswagen/
  • Models
    • TBD: /%brandname%/%modelname%/
  • Control Modules
    • /%kbidentifier%
      • /VCRNNXXXX
      • /VCRNNNNXXXX
  • Control Module Functions
    • VCRNNXXXX-ADP (Adaptation)
    • VCRNNXXXX-BS (Basic Setting)
    • VCRNNXXXX-COD (Coding)
    • VCRNNXXXX-LOG (Login/Coding-2)
    • VCRNNXXXX-SEC (Security Access)
    • VCRNNXXXX-SOT (Selective Output Test)
    • VCRNNXXXX-SP1 (Special Notes/Information/Functions 1)
    • VCRNNXXXX-SP2 (Special Notes/Information/Functions 2)
    • VCRNNXXXX-SPX (Special Notes/Information/Functions X)
  • Engines
    • /engines/
    • Industrial Engines
      • /engines/industrial/
    • Marine Engines
      • /engines/marine/
  • Transmissions
    • /transmissions/
      • TBD: /transmissions/%type%/
      • TBD: /transmissions/09G/
      • TBD: /transmissions/0AM/
  • Common Procedures
    • /common/
  • Retrofits
    • /retrofits/
      • VCRRXXXX
  • Fault Codes
    • /dtcs/ (General Information / Usage & Search)
    • /dtc/%dtcnumber%
      • /dtc/00003/ (Old VAG Scheme)
      • /dtc/B1032/ (OBD2/EOBD Scheme)
      • /dtc/C10AA/
      • /dtc/P0491/
      • /dtc/U25B6/
  • Information
    • /info/
    • Official Factory Repair Information
      • /info/repair/
    • Immobilizer
      • /info/immobilizer/
    • Component Protection
      • /info/component-protection/
    • Schutz der Fahrzeugdiagnose (SFD)
      • /info/sfd/
    • Common Acronyms
      • /info/acronyms/

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩

  2. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩