Skip to content

Documentation Guidelines

Documentation Guidelines

Your style, your words, and your tone define you. Correspondingly, this style guide lays out standard editorial instructions that define Shopware documentation.

We recommend that every contributor follows the defined writing standards to maintain uniformity of the documentation. Refer to different sections of this guide to know more.

Audience

It is important to consider the background of the potential audience reading your writing. This helps you to adapt your writing to meet their needs and interests.

Who is the audience?What are their roles?
Fullstack developer
  • Plugin development
  • Templates
  • Routes/ Controllers
Frontend developer
  • Admin
  • Themes
  • PWA
Backend developer
  • DI/ Service architecture
  • Message queues
  • DAL
  • Action event system
  • ElasticSearch
API developer
  • How to consume the API
  • Create a product/ category import
  • How to extend the API
  • API paradigm
  • Proper API references
  • Request collection
DevOps
  • Hosting setup
  • Deployment
  • Performance tests
Project/ Solution architect
  • Hosting
  • Architecture
  • Modules/ Extension system
  • Paradigms/ Patterns
  • Commonalities app system/ Plugin system
Designer
  • Component library
  • Design system
Product owner/ Manager
  • Responsibilities pertaining to the product life cycle
Tech writers
  • Document all product details

List of docs maintained by us

Word list

Choose ecommerce and technical terms from the pre-defined list of terminologies:

These are internal resources visible to Shopware employees only. :::

Use of third-party sources

Third-party sources include websites, books, blogs, videos, images, and more. Ensure to reference these external sources in the documentation only if they are trustworthy. Avoid copying any content directly from other sources like websites, encyclopedias, and Wikipedia.

Markdown rules

Adhere to the Markdown cheat sheet while creating the document.

Refer to GitBook syntax for features like hint block, emoji, API blocks, etc.

Symbols in Markdown sometimes serve multi-purpose. For example, * or - can be used to create bulleted lists. However, follow a single pattern to maintain uniformity throughout. Further sections describe the usage of these patterns and let us comply with them.

Also, user-defined rules govern the content quality, such as removing trailing spaces, code fence style, and more. You may refer to these rules in the Markdown style of Shopware docs.

The following section details the conceptual outline structure of our documentation.