crate / crate/cratedb-guide

Improve general guidance aka. easy user journey

Open
#227 0 comments 0 reactions 0 assignees View on GitHub
help wanted pitch
Dominant language
No language data
Stars
3
Forks
4
Avg merge
3d 18h
Merged PRs (30d)
1

Description

## About

> The developer documentation has grown organically over a decade. Its corpus is large, and for a first-time user of CrateDB, it can be difficult to find the information needed.

Improve relevant details.

## Details

- Overhaul "Getting Started" section.
- Provide tiny runnable examples to make pages actionable for newcomers.
- Rearrange the pages into a new menu better suited to support the user journey in adopting CrateDB. A few proposals for outlines exist already.
- Take the most critical pages supporting the user journey and clean them up. We also need to test the statements/snippets are correct.

## Background

- People have been voting for an easier user journey.
https://github.com/crate/tech-content/issues/143#issuecomment-3167655658

> Our goal is to produce clear, up-to-date, and working documentation of the data sources we support. Let’s keep it simple and focused, no need to explain basics (or insert low-value screenshots), as we’re writing for technically proficient users.

## References

- https://github.com/crate/tech-writing/issues/349
- https://github.com/crate/cratedb-guide/issues/10
- https://github.com/crate/roadmap/issues/32
- https://github.com/crate/cratedb-guide/issues/48
- https://github.com/crate/crate-tutorials/issues/61
- https://github.com/crate/tech-content/issues/42
- https://github.com/crate/cratedb-guide/issues/28
- https://github.com/crate/crash/issues/458

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the existing "Getting Started" section and review the outline proposals and linked documentation issues for the intended user journey. Identify the critical pages, create tiny runnable examples, and verify their statements and snippets; done means the navigation and guidance are reorganized, focused, current, and tested.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.