DEV Community

CrabPascal
CrabPascal

Posted on

Read This First: Three Onboarding Paths | Leia primeiro: três trilhas de entrada

#pascal #tutorial #beginners #documentation

Bilingual post · Post bilíngue

Jump to: English · Português

English {#english}

Read This First: Three Onboarding Paths

In post 032 we mapped the Mintlify site top-down. Now we zoom into the three entry documents every CrabPascal newcomer hits — and when to use each one without reading the same hello-world three times.

The trio is: leia-primeiro, comece-aqui, and quickstart. Together they replace the old monolithic README walkthrough.

Path A — "Where do I go?" (leia-primeiro)

Start here when someone opens the repo and feels lost. getting-started/leia-primeiro is a decision tree, not a tutorial. It asks what you want:

Goal Next pages
See what's implemented Status → feature lists
Understand internals Technical → architecture → challenges
Just run programs Quickstart → examples
Contribute code Status → technical → architecture
AI agent context Full technical stack + AI context pages

The golden-rule table ("Where is X?" → document N) is the fastest bookmark for teams. Spend five minutes here before sending a new hire down a rabbit hole.

Path B — "What is this project?" (comece-aqui)

getting-started/comece-aqui answers the product question: CrabPascal is a Rust Pascal compiler with OOP, generics, Horse REST APIs, and a VS Code extension. It lists flagship examples:

cd examples/
# ping-pong, time-server, api-completa, killer-app, crud, ...
Enter fullscreen mode Exit fullscreen mode

This page links outward to installation (INSTALL.md in repo), changelog, and release index. Use it in slide decks and conference intros — it's the "why should I care" narrative.

Extension install is one click away on the Marketplace (crabpascal.crabpascal). Point Delphi refugees here when they ask "is there an IDE story?"

Path C — "Make it run on my machine" (quickstart)

getting-started/quickstart is the hands-on path. Prerequisites, Windows binary vs cargo build --release, and the first program:

program HelloWorld;
begin
  WriteLn('Hello from CrabPascal!');
end.
Enter fullscreen mode Exit fullscreen mode 
crab-pascal run HelloWorld.dpr
crab-pascal check HelloWorld.dpr
Enter fullscreen mode Exit fullscreen mode

The CLI table defines daily commands:

Command Purpose
check Lex + parse + semantic; IDE-friendly diagnostics
run Execute via internal runtime
build-exe Emit C + compile with gcc/clang
preproc Expand {$IFDEF} directives

Cards at the bottom link to configuration TOML, VS Code integration, Postman guide, and project status — the natural "day two" reading list.

Choosing the right path for your audience

Delphi developer evaluating parity: comece-aqui → quickstart → examples/crud/ → compatibility review docs.

Rust contributor: leia-primeiro contributor branch → architecture → active sprint kickoff.

Teacher / bootcamp: quickstart → Horse CRUD example → compiler course in resources.

DevOps / CI: quickstart install section → check in pipeline → honest build-exe docs (post 040).

Anti-patterns to avoid

  1. Skipping leia-primeiro and reading 900-line historical guides — they may describe v1.5, not v2.22.
  2. Stopping at comece-aqui without running cargo test — enthusiasm dies without a green test line.
  3. Mixing FPC and Delphi assumptions — configure crabpascal.toml early (linked from quickstart).

Onboard a teammate in 15 minutes

Send this sequence:

  1. leia-primeiro — pick your row (2 min)
  2. quickstart — install + hello world (10 min)
  3. project status — note one red item to watch (3 min)

That's enough to join standup speaking the same language as the squad.

Next in series

Post 034 — Full IDE Integration connects the quickstart's check command to Problems panel, tasks, and debug workflows in VS Code and Cursor.

Português {#portugus}

Leia primeiro: três trilhas de entrada

No post 032 mapeamos o site Mintlify de cima para baixo. Agora entramos nos três documentos de entrada que todo novato no CrabPascal encontra — e quando usar cada um sem reler o mesmo hello-world três vezes.

O trio é: leia-primeiro, comece-aqui e quickstart. Juntos substituem o walkthrough monolítico do README antigo.

Trilha A — "Para onde eu vou?" (leia-primeiro)

Comece aqui quando alguém abre o repo e se perde. getting-started/leia-primeiro é uma árvore de decisão, não um tutorial. Pergunta o que você quer:

Objetivo Próximas páginas
Ver o que está implementado Status → listas de funcionalidades
Entender internals Técnico → arquitetura → desafios
Só rodar programas Quickstart → exemplos
Contribuir código Status → técnico → arquitetura
Contexto para IA Stack técnico + páginas de contexto IA

A tabela de regra de ouro ("Onde acho X?" → documento N) é o bookmark mais rápido para times. Gaste cinco minutos aqui antes de mandar um colega novo para um beco sem saída.

Trilha B — "O que é este projeto?" (comece-aqui)

getting-started/comece-aqui responde a pergunta de produto: CrabPascal é compilador Pascal em Rust com OOP, generics, APIs REST Horse e extensão VS Code. Lista exemplos carro-chefe:

cd examples/
# ping-pong, time-server, api-completa, killer-app, crud, ...
Enter fullscreen mode Exit fullscreen mode

A página liga instalação (INSTALL.md no repo), changelog e índice de releases. Use em slides e apresentações — é a narrativa "por que me importar".

A extensão instala em um clique no Marketplace (crabpascal.crabpascal). Aponte refugiados Delphi aqui quando perguntarem "tem história de IDE?".

Trilha C — "Rodar na minha máquina" (quickstart)

getting-started/quickstart é a trilha prática. Pré-requisitos, binário Windows vs cargo build --release, e o primeiro programa:

program HelloWorld;
begin
  WriteLn('Hello from CrabPascal!');
end.
Enter fullscreen mode Exit fullscreen mode 
crab-pascal run HelloWorld.dpr
crab-pascal check HelloWorld.dpr
Enter fullscreen mode Exit fullscreen mode

A tabela CLI define comandos do dia a dia:

Comando Função
check Lex + parse + semântica; diagnósticos amigáveis à IDE
run Executa via runtime interno
build-exe Emite C + compila com gcc/clang
preproc Expande diretivas {$IFDEF}

Cards no final ligam a TOML de configuração, integração VS Code, guia Postman e status — a leitura natural do "dia dois".

Escolhendo a trilha certa

Desenvolvedor Delphi avaliando paridade: comece-aqui → quickstart → examples/crud/ → review de compatibilidade.

Contribuidor Rust: ramo contribuidor do leia-primeiro → arquitetura → kickoff do sprint ativo.

Professor / bootcamp: quickstart → exemplo CRUD Horse → curso de compiladores em resources.

DevOps / CI: seção de instalação do quickstart → check no pipeline → docs honestas de build-exe (post 040).

Anti-padrões a evitar

  1. Pular leia-primeiro e ler guias históricos de 900 linhas — podem descrever v1.5, não v2.22.
  2. Parar no comece-aqui sem rodar cargo test — entusiasmo morre sem uma linha verde.
  3. Misturar suposições FPC e Delphi — configure crabpascal.toml cedo (link no quickstart).

Onboarding em 15 minutos

Envie esta sequência:

  1. leia-primeiro — escolha sua linha (2 min)
  2. quickstart — instalar + hello world (10 min)
  3. status do projeto — anote um item vermelho para acompanhar (3 min)

Isso basta para entrar no standup falando a mesma língua da squad.

Próximo da série

Post 034 — Integração IDE completa conecta o comando check do quickstart ao painel Problems, tasks e debug no VS Code e Cursor.

Published on dev.to/@crabpascal · Código em CrabPascal

Top comments (0)