Skip to content

docs: rewrite the org docs and add a style guide - #1

Merged
LKSNDRTMLKV merged 7 commits into
mainfrom
docs/dx-rewrite
Oct 27, 2026
Merged

LKSNDRTMLKV merged 7 commits into
mainfrom
docs/dx-rewrite

Conversation

@LKSNDRTMLKV

@LKSNDRTMLKV LKSNDRTMLKV commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Summary

Rewrites the organization's shared documents for an engineer evaluating or contributing to Odal Node, and adds DOCS-STYLE.md, the style guide the repository rewrites in dpp-core, dpp-engine and dpp-web follow. The guide asks for the command or code first and the reasoning after, mechanisms rather than virtues, one home per fact, a licence statement in the first sentence, explicit status labels for unfinished work, and no em dashes in prose.

Related issue

None. This is the org-wide half of the developer-first docs rewrite; the sibling PRs are docs/dx-rewrite in dpp-core, dpp-engine and dpp-web.

Changes

  • New DOCS-STYLE.md: audience and voice, page structure, words, punctuation, the licence statement, status labels, regulatory text, publication rules, and a pre-merge checklist.
  • Rewritten: README.md, profile/README.md, CONTRIBUTING.md, GOVERNANCE.md, SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md.
  • Templates: the default pull request template and the issue template config.yml.
  • docs: widen the profile's picture of the system: "How the pieces fit" now shows your systems and dpp-core feeding the node, the node and resolver on your infrastructure, and the six outside parties a node deals with: people scanning the code, credential holders, signature checkers, suppliers' passports, the EU registry and the back-up provider. Dotted lines mark what needs configuration. GS1 Digital Link is described as one kind of digital link. The org README's "one screen" rule for the profile is relaxed to match.
  • docs: say what the websites actually host: SUPPORT.md said the sites carry schemas and vocabulary. They carry documentation and demonstration data; those IRIs live on other hosts.
  • docs: record that the xml-sec fork is archived: the odal-node/xml-sec fork is archived (the engine uses the upstream crate from crates.io). The defaults table and CONTRIBUTING no longer list it, and the rule for forks stays.
  • docs: say where each kind of regulatory date lives: DOCS-STYLE.md now says passport dates are rendered from the instrument catalog (<PassportDate> and passportDateOf() in dpp-web, docs: read passport dates from the core catalog dpp-web#40), and every other regulatory date is written beside the article that sets it.
  • docs: move credits to CREDITS.md and widen them: the profile's credits section now links to a new CREDITS.md, organised by three tests: upstream maintainers who fixed what we reported (xml-sec, the EUDI SD-JWT library), the reference implementations dpp-core is tested against in CI (DSS, @sd-jwt/core, the GS1 Barcode Syntax Engine, aas-core3.0, aas-test-engines, pyld, the W3C DID Test Suite), and single-maintainer libraries in the signing and validation path (serde_jcs, jsonschema, qrcode, x509-verify).

Checklist

  • No secrets, credentials, keystores or .env files in the diff
  • No hard-coded version, date or deadline added to a document
  • Commits are signed off and carry no AI attribution
  • Founder review of the wording

Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
@LKSNDRTMLKV LKSNDRTMLKV added the documentation Improvements or additions to documentation label Oct 27, 2026
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
LKSNDRTMLKV and others added 2 commits October 27, 2026 19:31
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
@LKSNDRTMLKV LKSNDRTMLKV changed the title docs: rewrite the org docs for developers and add a docs style guide docs: rewrite the org docs and add a style guide Oct 27, 2026
@LKSNDRTMLKV
LKSNDRTMLKV merged commit baeffb5 into main Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant