diff --git a/BEST-PRACTICE.md b/BEST-PRACTICE.md new file mode 100644 index 00000000..9db8fc50 --- /dev/null +++ b/BEST-PRACTICE.md @@ -0,0 +1,123 @@ +# Quix Documentation Best Practice Guide + +This document describes the best practices used by Quix in writing technical documentation. In particular, it covers the main paradigm used in creating Quix documentation: topic-based writing. Topic-based writing is a long-established industry standard for writing web-based technical documentation. This guide also covers aspects of technical docs such as search, navigation, and information architecture. + +This is a companion document to our [Writing Style Guide](./WRITING-STYLE.md), which you should read to understand our "house style" for writing technical documentation. The style guide covers such details as tense, language, spelling, common technical terms, capitalization, section and topic headings, and many other aspects of writing Quix technical documentation. + +## What is topic-based writing? + +Topic-based writing has a long history in technical writing, becoming a significant paradigm with the creation of [DITA](https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture) in the early 2000s by IBM. The roots of DITA go back further, to SGML, which was invented by IBM in the 1960s. The DITA specification is currently managed by [OASIS](https://www.oasis-open.org/). + +It's important to note that while DITA (and SGML) are XML-based technologies, the key idea of topic-based writing can be expressed with any technology from XML to Markdown. + +So what is topic-based writing exactly? Topic-based writing (TBW) is an approach to writing technical information where you write material in focused, self-contained topics. There can be different topic types, such as concept, and task (sometimes called "how tos"). Topic types are discussed in more detail later. + +TBW is in contrast to the model that is commonly used in books and manuals, where you have a long progressional structure: you start at the beginning and read all the way to the end. The probem with the "linear progression" paradigm was found to be, after research, that almost nobody used technical documentation in this manner - they tended to dip into specific sections, or order to gain specific knowledge. + +This affinity with "just in time" information has been made even more true with the advent of web-based documentation, and the prevalence of search engines such as Google, and Q&A sites such as Stack Overflow. People tend to start with search, and look for an immediate solution to their current pain point, which may be, in practical terms, trying to understand a concept, or configure a specific part of the software. + +With TBW, combined with powerful integrated search, as well as the use of external search engines that index web-based documentation, as well as effective information architecture and navigation, readers can quickly locate the specific information required, without having to wade through a lot of extraneous information, that may be useful, but not at the current moment. + +**Note:** To prevent confusion with Kafka Topics, writers should avoid using the term "topic" in the main documentation, when referring to documentation. For example, rather than writing "In this topic...", use "In this documentation...", or "In the following sections...". + +## Topic types + +In common with industry-wide practices, Quix uses four main topic types in its technical documentation: + +1. Concept +2. How-To (sometimes called a guide) +3. Reference +4. Tutorial + +These types are very commonly used. They are explained in detail in Divio's excellent guide to [writing technical documentation](https://documentation.divio.com/). + +Summarizing Divio's guide, concepts help with understanding, how-tos with getting stuff done, reference topics are informational, and tutorials provide learning experiences. The latter should be briefly explained. While it is always desirable to learn something useful from working through a tutorial, their main function is to provide experience of using the product. That should ideally be a pleasant, and even fun, interaction. That is something that the technical writing team at Quix strives for. We want the explorations of the product to be fun, enjoyable, *and* informative. This way we believe the reader will come back for more, and explore all parts of the system, and eventually adopt the product as a solution to their own real-time streaming use cases. + +There's also an excellent [video presentation](https://www.youtube.com/watch?v=t4vKPhjcMZg) on the different topic types listed here, and their purpose. + +## What makes a good topic? + +A good topic should ideally be as focused and self-contained as possible. It should not ramble or try to cover too much information in the topic, as the reader will quickly become overwhelmed. By keeping the topic focused, and using good headings (see our [writing style guide](./WRITING-STYLE.md#section-headings)), the reader (such as a developer or data scientist) will be able to find the required information more easily, using the Quix documentation integrated search. + +## Search + +Good search is **critical** to effective TBW. For this reason, the Quix documentation features a powerful built-in search facility. External search engines such as Google are also supported, as the Quix documentation is generated as HTML, compliant with the latest W3C standards, and as such can be efficiently indexed by external search engines. + +The Quix documentation search facility is incremental - you start typing your search term, and the search engine starts to find matching topics immediately. Of course, the reader can also avail themselves of external search engines, and this is often their starting point before landing in the Quix documentation. When a reader lands inside the Quix documentation from an external source, navigation becomes critical, and this is explained in the next section. + +## Navigation and information architecture + +Good navigation is **critical** to effective TBW. Once a reader finds themselves in the Quix documentation, they need to be able to quickly orientate themselves on the page and in the documentation set overall. + +The main left-hand navbar, or TOC, provides the main element of the information architecture, and is purposely organized into the following top-level hierarchy: + +1. **Landing page and Quickstart**. The idea here is to quickly orientate the reader. From the landing page they can jump to key pieces of documentation. The Quickstart provides an easy way to "dip a toe" into Quix, and try the product out. The Quickstart is divided into two parts: one aimed at all users, and one specifically targeting developers. +2. **Quix Platform**. This is the main Quix product, and consists of the SaaS offering, UI, pipelines, deployments, and pre-built connectors and transforms. Concepts, How-Tos and Tutorials for Quix Platform are contained in here. +3. **Client Library**. The Quix Streams client library provides a very effective way to write scalable real-time streaming applications. Using Quix Streams you can create solutions that work with Quix Platform, or with other services depending on your requirement. The `Client Library` section also includes API reference documentation generated from source code for both the Python and C# versions of Quix Streams. +4. **APIs**. These are additional Quix APIs, other than those provided by Quix Streams. The documentation consists of general topics, as well as REST API references based on OAS3 documents. + +The longer topics can be navigated using the right-hand "on this page" TOC. This allows you to quickly navigate through the sections of a topic. It is important that topics are structured with the correct heading levels. There should only ever be one `h1` heading per topic, but there can be several `h2`s. Section headings below `h3` should be used sparingly, as they won't be displayed in the navigation, and could indicate the topic has become too convoluted. The solution can be to split the topic into multiple topics, or otherwise rethink the structure. + +It's important that the end of the topic should not leave the reader hanging, so a well-written topic ideally ends with a "Next steps" section, where the reader can find suggested resources that enable their Quix learning journey to continue. + +## Tutorials + +As mentioned before, tutorials not only serve to inform, but to provide a learning experience with the product. The reader should be left interested, informed, and **confident** to further explore the product. + +**IMPORTANT:** Tutorials that fail, because they are not maintained, create the opposite to the required experience - they leave the reader confused, and create an unpleasant (not very fun) experience. They leave the reader feeling disengaged, and reluctant to explore further. + +As tutorials tend to be longer-form material, Quix uses the approach of splitting the tutorials up into *parts*. This allows the reader to attempt a part, leave it to one side should they so wish, and then return to continue with the tutorial when time permits. To help the tutorial be manageable, each part is further divided into steps. Steps are numbered to provide an additional source of reference, and make working through the procedure easier to track. + +The Quix technical writing team attempts to keep the structure of each tutorial consistent, so that the layout for readers feels familiar. An example of this structure can be found in the [Sentiment Analysis tutorial](https://docs.quix.io/platform/tutorials/sentiment-analysis/index.html). Writers should always try to follow this structure consistently. + +Note this particular tutorial also includes optional parts. This is done to keep the main tutorial length reasonable - the longer the tutorial, the less likely the reader is to complete it, as they can get lost in the myriad steps and configurations. By keeping things as simple as possible, and providing optional parts as self-contained addendum, things are kept much more manageable. + +Another approach (and perhaps to be preferred), is to create a new separate tutorial that covers the optional or additional parts. This is not always possible though, as some steps may be required for both tutorials, and you want to avoid repeating steps unnecessarily. As a writer you use your best judgement at the time, but remember you can always circle back later with a view to improvements. + +## "Docs as code" and tooling + +Quix documentation uses a "docs as code" approach. What this means is the same tools that are used to manage code are used to manage documentation. There are numerous reasons for this. Primarily, it allows for easier contribution and participation, as tools and technologies, such as Git, GitHub, Markdown, issue trackers, and related workflows are familiar and widely adopted. + +Quix uses GitHub as the repository for the Markdown files that make up the Quix technical documentation, and contributors can avail themselves of full revision history, clones and forks, PRs, PR reviews, branches, tagging, and so on. + +The key tooling used for the Quix documentation includes: + +1. [GitHub](https://github.com/quixio/quix-docs) - repositories, issue tracking, PR reviews, revision control. +2. [Markdown](https://github.github.com/gfm/) - the source format for general Quix documentation is GitHub-flavoured Markdown. Our tooling also supports enhancements to this such as for tabbed codeblocks, code annotations, and a wide range of admonitions. +3. [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - this is our main documentation tooling. After extensive analysis of open source documentation tooling offerings, Quix decided on going with Material for MkDocs. This open source project works with already established technologies such as MkDocs and Python. It provides an unsurpassed documentation experience, with minimal configuration. Quix is an avid sponsor of the [insiders program](https://squidfunk.github.io/mkdocs-material/insiders/), which gives us access to numerous "goodies" that help make our documentation more effective. +4. [OpenAPI](https://swagger.io/specification/) - for REST APIs, Quix uses Open API Specification v3 documents. +5. [GitHub Actions](https://github.com/features/actions) - our build pipelines use GitHub Actions. These are used, for example, to create review apps. Review apps are complete builds of the documentation that can be used to assist in the review process. A link to the review app is automatically added to the docs repo pull request (PR). + +## Multiple repositories + +Quix uses multiple (currently two) repositories to manage the Quix documentation, these are: + +1. [Quix Docs](https://github.com/quixio/quix-docs) - this is the repository for general docs, Quix Platform docs, and API docs. +2. [Quix Streams](https://github.com/quixio/quix-streams) - a stand-alone repository for Quix Streams, including all Quix Streams documentation. + +Quix uses the MkDocs [multirepo plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) to import a complete repo and make it part of a documentation set. Quix uses this to import the Quix Streams documentation stored in the Quix Streams repo. + +## Docs we like + +We always look at what other companies are doing and try to follow best practices in documentation. Some documentation sites that the Quix team is impressed by include: + +* [Cockroach Labs](https://www.cockroachlabs.com/docs/) - great design and practical information architecture targeting users. +* [Aiven](https://docs.aiven.io/docs/platform) - a very nice example of the use of topic-based writing. +* [ReadySet](https://docs.readyset.io/) - another good example of topic-based writing, with crisp, clear design. They also use Material for MkDocs. + +## See also + +Other guides that may be useful if you are thinking of contribnuting to the Quix documentation: + +* [README](./README.md) - Contains basic introductory material to help you get started with the Quix documentation repository. +* [Contribution Guide](./CONTRIBUTING.md) - More detailed guide on how to contribute to the Quix documentation. +* [Writing Style Guide](./WRITING-STYLE.md) - Writing style guide covering the writing conventions to use in the Quix documentation. + +There are also books that cover best practices in great depth: + +* **DITA Best Practices** by Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt - although uses DITA, the ideas and techniques in this book are useful, even if you're not using DITA. +* **Every Page is Page One (Topic-based Writing for Technical Communication and the Web)** by Mark Baker (Foreword by Scott Abel) - excellent guide to the subject, and highlights the importance of navigation and search, including the role of external search engines. + +## Get in touch + +* [The Stream](https://join.slack.com/t/stream-processing/shared_invite/zt-13t2qa6ea-9jdiDBXbnE7aHMBOgMt~8g) - The Quix open source community on Slack. Feel free to sign up and ask further questions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 494aa492..a3d5424b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,33 +2,31 @@ You want to help improve our documentation? Fantastic! Here are a few guidelines to help you get started. -## Reporting Bugs and Requesting Enhancements +## Reporting bugs and requesting enhancements If you spot a mistake or see room for improvement in any of the Quix docs, please let us know! To create an issue, follow these steps: 1. Open the [GitHub issues](https://github.com/quixio/quix-docs/issues) page for the Quix documentation repository. -2. Click **New Issue** and enter a descriptive title that references affected page. - For example, '_Sentiment Analysis tutorial references a button that doesnt exist_'. +2. Click **New Issue** and enter a descriptive title that references affected page. For example, '_Sentiment Analysis tutorial references a button that doesnt exist_'. 3. Click **Submit Issue** and wait for one of our team to respond. We'll try to respond within a couple of working days. - -## How Do I Submit a Good Docs Issue? +## How do I submit a good docs issue? Make sure your title is clear and descriptive. For any problem or enhancement, describe it in full, including any expected results and how they differ from the real results. The more descriptive your issue is, the quicker we'll be able to resolve your issue. -## Contributing Changes +## Contributing changes If you want to fix an issue yourself, go ahead! We welcome edits. For small changes, like typos and minor clarification, you can do an online edits in the GitHub Editor. If you want to do more, or if you prefer to work offline, you can fork this repo, add your changes locally and then push to your fork. After that, you can create a pull request to merge your changes into the original docs repository. -For more information on writing docs see the [Quix Writing Style Guide](GUIDE.md). +For more information on writing docs see the [Quix Writing Style Guide](WRITING-STYLE.md) and the [best practice guide](./BEST-PRACTICE.md). -**Note:** Please create forks or branches from the 'dev' branch. +**IMPORTANT:** Please create forks or branches from the `dev` branch. -## Online Edits in the GitHub Editor +## Online edits in the GitHub Editor If you want to make a change, you can do it right on GitHub. Just follow these steps: @@ -40,7 +38,7 @@ This will open the relevant page in GitHub **Note:** Remember to create forks or branches from the 'dev' branch. -## PR Reviews +## PR reviews A member of our team will review your pull request. We might give feedback and suggestions for how you could improve the pull request, which is the same process we use when reviewing each others work internally. We'll try to respond within a couple of working days, but feedback can sometimes take longer. We appreciate all your feedback and contributions. diff --git a/README.md b/README.md index 9d76fd20..a21c112b 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,25 @@ [![Build](https://github.com/quixio/quix-docs/actions/workflows/sync-build-deploy.yaml/badge.svg)](https://github.com/quixio/quix-docs) -This repository is the source content for the Quix documentation that is published on the web at https://quix.io/docs. +This repository is the source content for the Quix documentation that is published on the web at https://quix.io/docs. The source files for the documentation are in GitHub-flavoured Markdown, with additions supported by our tooling, [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). To get a free Quix account, [sign up](https://portal.platform.quix.ai/self-sign-up). -## Prerequisites +## Contributing + +If you would like to contribute to these docs, see the [Contribution Guide](./CONTRIBUTING.md). + +If you create a PR on the docs `dev` branch, a review app consisting of a complete rendered docs build is created automatically for you, so you can preview your changes there. Currently, to rebuild the docs after pushing up any further changes, you need to close and reopen your PR. + +**IMPORTANT:** All docs PRs should be raised against the `dev` branch. + +If you plan to make more than basic changes to the documentation, you should also become familiar with the Quix [Writing Style Guide](./WRITING-STYLE.md) and the [Best Practice Guide](./BEST-PRACTICE.md). + +## Running docs locally + +The following is only required if you are part of the Quix technical writing team, or you contribute frequently, and want to check your docs PR locally before pushing up. Otherwise, the simplest approach is to refer to the review app that is created automatically for you, when you push up a PR on the `dev` branch. + +### Prerequisites To run these docs locally you'll need: @@ -16,7 +30,25 @@ To run these docs locally you'll need: * Sign up to the [Insiders Programme](https://squidfunk.github.io/mkdocs-material/insiders/), if you want to see all features rendered locally. * A Git client (the command line is fine). -## Running the docs locally +### Plugins used + +If you want to fully render all documentation locally you will need to install the following plugins with `pip install`: + +* [glightbox](https://pypi.org/project/mkdocs-glightbox/0.1.0/) +* [multirepo](https://pypi.org/project/mkdocs-multirepo/) +* [redirects](https://pypi.org/project/mkdocs-redirects/) + +You will also need to sign up to the [Insiders Programme](https://squidfunk.github.io/mkdocs-material/insiders/). + +The [social plugin](https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/) is also used to automatically provide metadata. See the [social plugin documentation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/) for details on how to install the dependencies of the plugin. You might also need to first install `cffi` with `pip install cffi`, if not present on your system. + +### Linked repositories + +This repo uses the `multirepo` plugin to pull in client library content from the [Quix Streams repo](https://github.com/quixio/quix-streams). + +You can read more about Quix Streams [here](https://github.com/quixio/quix-streams/blob/main/README.md). + +### Viewing the docs To view the docs locally: @@ -30,16 +62,6 @@ To view the docs locally: 4. Run `mkdocs serve`. 5. Navigate your browser to `localhost:8000` to view the docs. -## Linked repositories - -This repo uses the `multirepo` plugin to pull in content from the [Quix Streams repo](https://github.com/quixio/quix-streams). - -You can read more about Quix Streams [here](https://github.com/quixio/quix-streams/blob/main/README.md). - -## Contributing - -If you would like to contribute to these docs, see the [contribution guide](./CONTRIBUTING.md). - ## Getting in touch The best way to contact us is through our public Slack channel, [The Stream community](https://quix.io/slack-invite). Please sign up, and introduce yourself! diff --git a/GUIDE.md b/WRITING-STYLE.md similarity index 89% rename from GUIDE.md rename to WRITING-STYLE.md index 34c43494..9bac52bf 100644 --- a/GUIDE.md +++ b/WRITING-STYLE.md @@ -75,6 +75,12 @@ Use the following guidelines for industry-standard terms, and Quix terms: * DevOps, never devops * Startup and scale-up +## Use topic-based writing + +You can read about the Quix approach to topic-based writing in the [companion guide](./BEST-PRACTICE.md). + +**Note:** To prevent confusion with Kafka Topics, writers should avoid using the term "topic" in the main documentation, when referring to documentation. For example, rather than writing "In this topic...", use "In this documentation...", or "In the following sections...". + ## Use International English The company standard is, as with most software companies, to use International English. This is [defined](https://www.star-ts.com/about/translation-faq/what-is-international-english) as US spelling, with Americanisms removed. @@ -288,6 +294,14 @@ If you do need to use title case, you can use one of the widely available [tools So, unless there is a good reason not to, use sentence case (first letter is capitalized). +## Section headings + +There should only be one top-level section heading per topic (`h1`). Section headings below `h3` should be avoided, as they do not show in the "on this page" table of contents, and so important information can be missed. Instead, rethink the topic structure, or create an additional new topic if required. + +### Make section headings informative + +Make topic and section headings as precise and informative as possible. For example, "How to configure RAM in a deployment" is more useful as a topic title than "Deployments". It indicates the topic content is of "how to" type, and precisely identifies the configuration being performed. It may be that related material can be conveniently collected into a single topic without the topic length becoming excessive. You might perhaps have "How to configure a deployment" and then have sub-headings for RAM, CPU, Type, Replicas, and so on. Use your best judgement. + ## Bulleted lists This is an example of a bulleted list: @@ -340,6 +354,16 @@ Make sure you write the correct case for product names: * macOS not Mac OS * .NET not .Net or .net +## Links + +Avoid excessive interlinking (use links sparingly), as readers tend to link hop and soon get disorientated. Consider having a "next steps" section at the end of a topic with cross-references to useful material. This allows readers to progress through the material without distraction, and thenpursue additional information should they require it. + +External links should open in a new tab. This can be achieved by constructing links using `{target=_blank}`, as follows: + +``` +[Link text](URL){target=_blank} +``` + ## Other considerations Some additional points to bear in mind: @@ -362,6 +386,10 @@ Some further examples of writing style guides are: * [Vonage/Nexmo](https://developer.nexmo.com/contribute/guides/writing-style-guide) * [Ably](https://github.com/ably/docs/blob/main/writing-style-guide.md) +## See also + +* [Best Practice Guide](./BEST-PRACTICE.md) - the Quix guide to how we do documentation. + ## Contact To get in touch with us, please join [The Stream community](https://quix.io/slack-invite?_ga=2.132866574.1283274496.1668680959-1575601866.1664365365). diff --git a/docs/apis/data-catalogue-api/intro.md b/docs/apis/data-catalogue-api/intro.md index 1619fe21..2da784cc 100644 --- a/docs/apis/data-catalogue-api/intro.md +++ b/docs/apis/data-catalogue-api/intro.md @@ -21,11 +21,11 @@ You’ll also need to have some data stored in the Quix platform for API use to be meaningful. You can use any Source of our [Quix Library](../../platform/samples/samples.md) to do this using the Quix portal. -## Topics covered +## Further documentation | | | | | ------------------------------------------------------------------ | ------------------ | ----------------------------------------- | -| Topic | Endpoint | Examples | +| Documentation | Endpoint | Examples | | [Streams, paged](streams-paged.md) | `/streams` | Get all streams in groups of ten per page | | [Streams, filtered](streams-filtered.md) | `/streams` | Get a single stream, by ID | | | | Get only the streams with LapNumber data | diff --git a/docs/apis/streaming-reader-api/intro.md b/docs/apis/streaming-reader-api/intro.md index 7d7e087d..fb383bd2 100644 --- a/docs/apis/streaming-reader-api/intro.md +++ b/docs/apis/streaming-reader-api/intro.md @@ -7,7 +7,7 @@ happen. The examples shown use the Microsoft [SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-5.0){target=_blank} JavaScript client library. -## Topics +## Documentation - [Set up SignalR](signalr.md) diff --git a/pull_request_template.md b/pull_request_template.md new file mode 100644 index 00000000..6b1673ae --- /dev/null +++ b/pull_request_template.md @@ -0,0 +1,11 @@ +## Description + +A PR description indicating the purpose of the PR. + +* [Ticket](link) + +## Review + +Instructions on how to review the PR. + +* [Page to review](link)