Docs portal

[rannn505]

Suggestion

• Develop a new documentation portal with its content and source code hosted within this repository.
• Utilize a robust documentation platform; potential options include:
  • Docusaurus
  • Mintlify
• Migrate existing content from Configu Docs.
• Set up the portal deployment at docs.configu.com.
• Author new sections such as: internals, API Reference, Contributing, Integrations, etc.
• Enrich visuals all over including graphs, images, videos, live code editors, Admonitions (WIP), etc.

Motivation

• Encourage and increase contributions to the documentation.
• Synchronize updates between code and documentation, ensuring they reflect each other accurately and are up-to-date.

Context

No response

[rannn505]

Spec

Selected:
Mintlify as documentation PaaS - https://configu-preview.mintlify.app/

Structure:

• Ancestors
  • Docs
  • Guides
  • Videos
  • Contributing
  • Change-Log
  • Chat

[RichardAkman]

Preliminary docs portal review

Following an initial review of the docs portal at its current state (10/04/2024), I'm writing my notes here.

My overall impression is very positive, the docs structure seems more intuitive and the copy is great.

General notes

• The dark theme background is too dark, I think it should be the same as the platform.
• The border colors in the dark theme are hard to see.
• The divider in white theme at the top of the page is very hard to see.
• "Guides" in the sidebar doesn't redirect anywhere right now.
• "Suggest edits" currently point to a broken link.
• There's a bug with the "Read more" component - when a lot of huge ones are open it causes the table of contents to be inaccurate
  
• The AI feature doesn't seem to work or I don't know how to trigger it
• The search result here seems wrong
  

Introduction section

Overview page

• Interfaces - .configu - the emoji feels very out of place there
• Interfaces - IDE extensions - "auto-completion from configs in your code" confusing and unclear phrasing. I'm not sure what this means.
• Tooltips have a lot of **<text>** which seems weird, is it supposed to be bold?
  • Edit suggestion to improve phrasing:
    • Before: Software configurations refer to the data that determines how a software application or system behaves. As codebases continuously expand and become more branched and complex, it may require more configuration data to customize its behavior and ensure that it functions correctly.
    • After: Software configurations refer to the data that determines how a software application or system behaves. As codebases continuously expand and become more branched and complex, they may require more configuration data to customize their behavior and ensure they function correctly.

Comparison page

• writeability -> writability

Concepts page

• Cfgu -> .cfgu $schema reopens the same page
• ConfigStore - Stores Collection is currently a broken link - and not target blank
• Upsert command + eval command - Fix grammar: coralated -> correlated and acutal -> actual
• Export command + eval command - read more is wrong, seems like a copy paste from upsert read more

[RonConfigu]

Following Richard's instructions to review the new docs

As requested by Richard, below are my findings on "broken links" and my input on some of the "copy/content"

https://docs.configu.com/introduction/concepts

• .../concepts#cfgu: .cfgu $schema leads to homepage
• .../concepts#configstore: ConfigStore Collection leads to homepage

https://docs.configu.com/interfaces/.cfgu#schema

• Why the schema file is under draft? making me feel like it is not ready.
• https://json-schema.org/draft/2020-12/schema-cfgu response 404

https://docs.configu.com/interfaces/.configu#schema

• Why the schema file is under draft? making me feel like it is not ready.
• $schema url has two values.
  1. https://json-schema.org/draft/2020-12/schema-configu - 404
  2. https://json-schema.org/draft/2020-12/schema - 200

https://docs.configu.com/interfaces/cli/overview

• .../overview#reference: configu.com/docs/commands leads to homepage / 404

https://docs.configu.com/interfaces/sdk/overview

• .../overview#node-js-sdk: /interfaces/sdk/nodejs i've never seen hyper-link with relative path like that.
• .../overview#browser-sdk: /interfaces/sdk/browser i've never seen hyper-link with relative path like that.

https://docs.configu.com/integrations/store/configu/tokens

• A token can optionally be given an expiration date.: I don't see this setting in production.

https://docs.configu.com/guides/hello-world

• .../hello-world#2-declare-your-first-configschema: Declare is not the right word here in my opinion. making me feel like i have to use configu init everytime to declare the schema.

https://docs.configu.com/integrations/store/configu

• In my opinion Platform should have its own section even though it is a store.
• .../configu/config-explorer: assuming the new grid/graph this is all outdated.

[RichardAkman]

Extended docs portal review

Following my previous initial review, here are my notes regarding the rest of the docs that have since been added.

• Overview/configschema-and-cfgu page
  • .cfgu.json - maybe give an indication that YAML is also supported. This is done in the interfaces/.cfgu page but not here
  • Plug and Play - for example this feels like a great place to link to a guide
  • There are many instances that .cfgu is wrapped with backticks, this seems to be a "rule". There are two instances in this page where they aren't wrapped in backticks, is this intentional?
• .cfgu page
  • I suggest that the properties be arranged by required first (which is currently only type) and then optional properties
  • I suggest that we link JSONSchema references (or at least one) to the JSONSchema website
  • ISO-based types like language or locale should specifically mention that they correspond to their respective ISO. Possible with a link to the ISO. This is even done for DateTime so it's pretty much a must.
• .configu page
  • The scripts property section seems to have a section from the scripts section mistakingly. This text seems wrong here: To define a custom script, add a new key-value pair to the schemas section of the .configu file, where the key represents the friendly name, and the value is the schema absoulte or relative path.
• Configu CLI/Overview page
  • installation process,this guide, configu.com/docs/commands - broken links
• Configu CLI/Reference
  • When clicking any of the links under commands sometimes the sidebar menu title corresponding to the heading flickers. View the attached video. I'd check other pages with a similar layout for the same issue.
    https://github.com/configu/configu/assets/47181182/7b275932-1df0-44ea-bd1b-b6afe022f109
• Integrations section
  • Should we start documenting store pages?
  • A lot of icons are hard to see in the dark theme. All the black ones to be precise.
  • The last heading ("app") is not highlighted in the sidebar when scrolling to the bottom of the page.
  • Both of the issues above can be seen in this image:
    
• Integrations/Configu/Overview page
  • The History & Versioning link points to configs editor - definitely a mistake but there's currently nothing that points to the editor. Is something possibly missing from the list?
• Guides/Hello-World page
  • There is an inconsistency in semantics in terms of what we call our SaaS, sometimes it's Configu Platform and sometimes it's Configu Cloud. Are the terms interchangeable in terms of the docs or is this a mistake we should fix? I think it should only be called Configu Platform in client-facing environments to prevent confusion
• Guides/hashicorp-vault page
  • Step 2 - The snippets that overflow end up showing up below the copy button, we had this problem in our platform too.