Using jargon and terminology to make it easier to write documentation

We had an open issue to bring back the jargon functionality, and that has now been implemented.

The implementation is different from back in the NextJS days (for those with long memory) and I would argue it’s better :innocent:

Jargon

Defining jargon

Jargon are terms that may be confusing to people who are new to FreeSewing. on FreeSewing.eu, we use everything that is defined under /docs/sewing for this. On FreeSewing.dev there is a dedicated jargon folder (in the site root) where you can create jargon entries.

The main thing to keep in mind is that a jargon term will turn into a button you can click, and it will load the docs in the modal window.

Using jargon

To use a jargon term, you just have to emphasise it:

Terminology

Defining terminology

This is done automatically. Terminology are things that we commonly use, yet linking to them all the time gets tired quick. On FreeSewing.eu, all of the design names are treated as terminology. So if in the documentation, blog post of showcase post you write aaron that will automatically be rendered as a link to /designs/aaon and turned into Aaron A-Shirt.

On FreeSewing.dev, the entire core API is treated as terminology. So you can do pattern or point.shiftfractiontowards and it will be rendered as a link to the relevant API docs.

Examples

On FreeSewing.eu

On FreeSewing.dev

1 Like