mirror
/
kickstart.nvim
mirror of https://github.com/nvim-lua/kickstart.nvim.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity
kickstart.nvim/docs/DOCUMENTATION-PLAN.md

9.8 KiB
Raw Blame History

📋 Documentation Plan & Status

✅ Completed

1. Changed to in Cheatsheet

  • Updated lua/plugins/core/cheatsheet.lua
  • All 105 instances of <Space> changed to <Leader>
  • Ensures consistency with which-key display

2. Created New Professional README.md

  • Location: README.new.md (ready to replace README.md)
  • Features: Badges, features list, requirements, quick start
  • Links to comprehensive documentation structure
  • Professional appearance with emojis and formatting

3. Created Documentation Structure

docs/
├── README.md                      # Main documentation index ✅
├── getting-started/
│   ├── README.md                  # Getting started overview ✅
│   ├── installation.md            # Detailed install steps (TODO)
│   ├── first-steps.md             # First hour tutorial (TODO)
│   ├── quick-reference.md         # Essential commands (TODO)
│   └── philosophy.md              # Design principles (TODO)
├── keymaps/
│   ├── README.md                  # Keymaps overview ✅
│   ├── core.md                    # Leader key bindings (TODO)
│   ├── lsp.md                     # LSP commands (TODO)
│   ├── plugins.md                 # Plugin-specific (TODO)
│   ├── debug.md                   # Debug keymaps (TODO)
│   ├── consistency.md             # Cross-plugin patterns ✅ (copied)
│   └── duplicates.md              # Duplicate keys guide ✅ (copied)
├── plugins/
│   ├── README.md                  # Plugins overview (TODO)
│   ├── core.md                    # Telescope, Neo-tree, which-key (TODO)
│   ├── editor.md                  # TreeSitter, mini.nvim, etc (TODO)
│   ├── lsp.md                     # LSP & completion (TODO)
│   ├── debug.md                   # nvim-dap (TODO)
│   ├── git.md                     # Git integration (TODO)
│   └── ui.md                      # UI enhancements (TODO)
├── languages/
│   ├── README.md                  # Languages overview (TODO)
│   ├── flutter.md                 # Flutter/Dart guide (TODO)
│   ├── rust.md                    # Rust guide (TODO)
│   ├── python.md                  # Python guide (TODO)
│   ├── svelte.md                  # Svelte guide (TODO)
│   ├── typescript.md              # TypeScript guide (TODO)
│   ├── go.md                      # Go guide (TODO)
│   └── others.md                  # Other languages (TODO)
├── vim-mastery/
│   ├── README.md                  # Vim mastery overview ✅
│   ├── week-01-motions.md         # Motion basics ✅
│   ├── week-02-text-objects.md    # Text objects (TODO)
│   ├── week-03-advanced.md        # Advanced editing (TODO)
│   ├── week-04-macros.md          # Macros & registers (TODO)
│   ├── week-05-cmdline.md         # Command line (TODO)
│   ├── week-06-windows.md         # Windows & tabs (TODO)
│   ├── week-07-search.md          # Search & replace (TODO)
│   ├── week-08-marks.md           # Marks & jumps (TODO)
│   ├── tips-and-tricks.md         # Productivity tips (TODO)
│   ├── workflows.md               # Real-world patterns (TODO)
│   └── advanced.md                # Advanced topics (TODO)
├── customization.md               # Customization guide (TODO)
├── plugin-development.md          # Plugin dev (TODO)
├── performance.md                 # Performance tuning (TODO)
├── troubleshooting.md             # Troubleshooting (TODO)
├── migration.md                   # Migration guide (TODO)
└── faq.md                         # FAQ (TODO)

📝 Files to Remove/Consolidate

Remove (Redundant)

  • NEO-TREE-CHEATSHEET.md - Incorporated into docs/keymaps/plugins.md
  • ORGANIZATION.md - Internal planning doc, not needed for users

Move to Archive or Remove

  • TESTING.md - Move to docs/development/ or remove
  • MIGRATION.md - Move to docs/migration.md
  • SETUP-GUIDE.md - Consolidate into docs/getting-started/installation.md
  • INSTALLATION.md - Consolidate into docs/getting-started/installation.md

Keep but Update

  • LICENSE.md - Keep at root
  • README.md - Replace with README.new.md
  • lazy-lock.json - Keep (Lazy.nvim uses this)

🎯 Next Steps (Priority Order)

Phase 1: Core Documentation (High Priority)

  1. Replace README.md with README.new.md

  2. Complete getting-started/

    • installation.md (consolidate INSTALLATION.md + SETUP-GUIDE.md)
    • first-steps.md (interactive tutorial)
    • quick-reference.md (one-page cheat sheet)
    • philosophy.md (design decisions)

  3. Complete keymaps/core.md

    • Consolidate KEYMAPS.md
    • Organize by category
    • Add examples

  4. Complete keymaps/lsp.md and keymaps/plugins.md

    • Document all LSP keymaps
    • Document Telescope, Neo-tree, Git, etc.

Phase 2: Plugin Documentation (Medium Priority)

  1. Create plugins/core.md

    • Telescope deep dive
    • Neo-tree features
    • which-key customization

  2. Create plugins/lsp.md and plugins/debug.md

    • LSP configuration
    • Mason setup
    • Debug adapter setup

Phase 3: Language Guides (Medium Priority)

  1. Create language guides
    • flutter.md (full Flutter tools guide)
    • rust.md (Crates.io integration)
    • python.md (virtual envs, testing)
    • Others as needed

Phase 4: Vim Mastery (Ongoing)

  1. Complete Vim mastery weeks 2-8

    • week-02-text-objects.md
    • week-03-advanced.md
    • week-04-macros.md
    • week-05-cmdline.md
    • week-06-windows.md
    • week-07-search.md
    • week-08-marks.md

  2. Create supplementary guides

    • tips-and-tricks.md
    • workflows.md
    • advanced.md

Phase 5: Advanced Topics (Low Priority)

  1. Create advanced guides
    • customization.md
    • plugin-development.md
    • performance.md
    • troubleshooting.md
    • faq.md

🎨 Documentation Style Guide

Writing Principles

  1. Clear and Concise: Get to the point quickly
  2. Example-Driven: Show, don't just tell
  3. Progressive Disclosure: Basic → Intermediate → Advanced
  4. Actionable: Every guide includes exercises
  5. Searchable: Good headers, keywords, cross-references

Formatting Standards

  • Emojis for visual hierarchy: 🎯 🔥 💡 ⚠️ 📚
  • Code blocks with language: vim, lua, ```bash
  • Tables for comparisons: Keymap tables, feature matrices
  • Callouts: Tips, Warnings, Notes
  • Navigation: Links at top and bottom of every page

File Naming

  • Use kebab-case: week-01-motions.md
  • Be descriptive: lsp-configuration.md not lsp.md
  • Group by prefix: week-01-, week-02-, etc.

📊 Estimated Completion Times

Already Done (4 hours)

  • ✅ Cheatsheet →
  • ✅ README.new.md
  • ✅ docs/README.md
  • ✅ docs/getting-started/README.md
  • ✅ docs/keymaps/README.md
  • ✅ docs/vim-mastery/README.md
  • ✅ docs/vim-mastery/week-01-motions.md
  • ✅ Copied consistency.md and duplicates.md

Phase 1 (8 hours)

  • getting-started/ guides (4 hours)
  • keymaps/core.md (2 hours)
  • keymaps/lsp.md (1 hour)
  • keymaps/plugins.md (1 hour)

Phase 2 (6 hours)

  • plugins/ guides (6 hours total)

Phase 3 (8 hours)

  • language guides (8 hours total)

Phase 4 (12 hours)

  • Vim mastery weeks 2-8 (9 hours)
  • tips/workflows/advanced (3 hours)

Phase 5 (6 hours)

  • Advanced topics (6 hours)

Total Estimated: ~44 hours of documentation writing

🎯 Immediate Action Items

Right Now

  1. Backup old README.md

    mv README.md README.old.md
mv README.new.md README.md

  2. Remove redundant files

    rm NEO-TREE-CHEATSHEET.md
rm ORGANIZATION.md

  3. Clean up root directory

    mkdir archive
mv KEYMAPS.md archive/
mv CONSISTENCY.md archive/  # Now in docs/keymaps/
mv DUPLICATES.md archive/   # Now in docs/keymaps/

Next Session

  1. Write getting-started/installation.md

    • Consolidate INSTALLATION.md and SETUP-GUIDE.md
    • Add macOS, Linux, Windows sections
    • Include troubleshooting

  2. Write getting-started/first-steps.md

    • Interactive 30-minute tutorial
    • Essential keymaps only
    • Real code examples

  3. Write getting-started/quick-reference.md

    • One-page PDF-printable guide
    • 50 most-used commands
    • Organized by category

💡 Content Sources

From Existing Files

  • KEYMAPS.md → docs/keymaps/core.md
  • CONSISTENCY.md → docs/keymaps/consistency.md ✅
  • DUPLICATES.md → docs/keymaps/duplicates.md ✅
  • INSTALLATION.md + SETUP-GUIDE.md → docs/getting-started/installation.md
  • lua/ plugin files → docs/plugins/ and docs/languages/

From Configuration

  • lua/config/keymaps.lua → keymap docs
  • lua/plugins/ → plugin guides
  • lua/plugins/lang/ → language guides
  • Comments in code → feature documentation

Original Content Needed

  • Vim mastery guides (weeks 2-8)
  • Tips and tricks
  • Workflows
  • Troubleshooting
  • FAQ
  • Customization guide

🔄 Maintenance Plan

Weekly

  • Update any changed keymaps
  • Add new plugin documentation
  • Review and improve based on feedback

Monthly

  • Check all links still work
  • Update screenshots if needed
  • Add new tips discovered

Per Release

  • Update version numbers
  • Document new features
  • Archive old migration guides

🎊 Success Criteria

Documentation is complete when:

  • ✅ New users can install and be productive in 1 hour
  • ✅ All keymaps are documented with examples
  • ✅ All plugins have usage guides
  • ✅ Complete Vim mastery path (8 weeks)
  • ✅ Troubleshooting covers common issues
  • ✅ Users say "I found it in the docs" instead of asking

Documentation is a journey, not a destination!

This plan provides the structure. Now we execute, one file at a time.