Article types
All articles should include a short introduction before any section headers. A good introduction provides enough information about the topic to let the reader determine if they’re reading the correct article to achieve their goal.
When relevant, all articles should link to another related article. For example, a reference or how-to article can link to the related concept article. However, don’t link to another article for the sake of linking to another article.
Most articles on the Lucidworks docs site are one of three types: concept, how-to, or reference. The three article types provide different perspectives on the same topic depending on the depth of information the user is seeking.
Concept
A concept article provides a high-level overview of a topic. It introduces the user to a topic without overwhelming them with every situation the topic is relevant for.
Because concept articles are high-level, the audience is just as wide. Expect anyone from search engineers to product managers to read your article. Each of them should come away with some understanding of the article’s topic.
In general, if an article isn’t a how-to or a reference article, write it like a concept article.
Properties of concept articles:
-
Provide a high-level overview of a topic
-
Assume little previous knowledge of a topic. You may assume intelligently; for example, if a user is reading an article about data sources, it’s safe to assume they know what a Fusion or Springboard app is. If in doubt, link to another concept article; that’s why they’re there.
-
Does not provide step-by-step instructions for completing tasks
Example concept articles:
How-to
A how-to article provides step-by-step instructions for completing a task. These articles explain how to do almost anything with the Lucidworks products: how to get started with a product, create an experiment, or automate a process.
The target audience of the typical how-to article is a user who wants to complete a task, whether the task is setting up an environment or digging deeper into a concept.
Properties of how-to articles:
-
The article contains a series of steps to complete a task.
-
The instructions must work.
-
The article shouldn’t leave the user halfway through a task. The article may be one in a series to complete a larger task, but the user should complete a concrete task in a how-to article.
-
Limits explanations and discussions of the concepts at hand. You may assume the user has a basic understanding of the concept, and a brief reminder with a link back to the relevant concept article is helpful. For example, you can assume the user knows what facets are when writing how to set up facets.
Example how-to articles:
Reference
Reference articles provide more details than concept articles. Reference articles include information such as configuration options, API parameter names and values, and supported data types.
The target audience of the typical reference article is a developer or search engineer configuring Lucidworks products for their organization.
Properties of reference articles:
-
Include an introduction so users understand when or if they would use the material on the page.
-
Describe configuration options, values, and how to use those values.
-
Include required fields and values.
-
Include allowed values when the list of allowed values is small.
-
Link to the relevant concept article to explain the topic further.
-
Use examples and code samples wisely. Complex examples that illustrate more than a basic understanding of the reference topic belong in their own how-to article.
Example reference articles:
See the Writing APIs section for more information on writing APIs in Stoplight.
Release notes
| This section currently describes Fusion release notes. |
Release notes provide information for a product release. These articles are labeled as reference in the frontmatter.
Write dates in Month DD, YYYY format. Spell out all months in full. Do not separate the month and year with a comma.
- Recommended
-
✅ January 26, 2022
- Not recommended
-
✘ 26 January 2022
- Not recommended
-
✘ 26 Jan. 2022
- Not recommended
-
✘ 1/26/22
Release notes include the following sections. Do not include a section when it does not apply (for example, if there are no deprecations). Include subsections within each section for each product or product type.
-
New features
-
Improvements
-
Other changes
-
Addressed security vulnerabilities
-
Bug fixes
-
Known issues
-
Deprecations
-
Removals
Example release notes articles:
The sidebar
Concept and reference articles appear in the sidebar. Because of the sidebar’s structure, the articles are ordered in the frontmatter.
The page named index.asciidoc is the parent page in the sidebar and may have articles nested underneath it.
The following example uses part of Fusion’s "Getting Data In" section in the sidebar.
..
|-- Getting Data In (https://doc.lucidworks.com/fusion/5.4/3218/getting-data-in)
|-- blob-storage.asciidoc
|-- importing-signals.asciidoc
|-- index.asciidoc
|-- parallel-bulk-loader.asciidoc
|-- Indexing
|-- index.asciidoc
|-- [other folders and articles]Getting Data In/index.asciidoc is the article that the Getting Data In URL links to. The Indexing folder also expands, and its article is the index.asciidoc contained within that folder.
When writing an article that has other articles nested underneath it in the sidebar, do more than repeat the sidebar in the parent article. It’s okay for these parent articles to be short, but they should still serve a purpose because they appear in search results.
- Recommended
-
✅ Fusion’s Getting data out article provides a summary of what a user can find in that section’s articles while summarizing what the concepts mean.