Repository navigation
docs: rewrite the org docs and add a style guide - #1
Merged
Merged
Conversation
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>
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
5 of 6 tasks
Signed-off-by: chillin_since_26 <aleksandar.temelkov@live.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-rewritein dpp-core, dpp-engine and dpp-web.Changes
DOCS-STYLE.md: audience and voice, page structure, words, punctuation, the licence statement, status labels, regulatory text, publication rules, and a pre-merge checklist.README.md,profile/README.md,CONTRIBUTING.md,GOVERNANCE.md,SECURITY.md,SUPPORT.md,CODE_OF_CONDUCT.md.config.yml.docs: widen the profile's picture of the system: "How the pieces fit" now shows your systems anddpp-corefeeding 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.mdsaid 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: theodal-node/xml-secfork 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.mdnow says passport dates are rendered from the instrument catalog (<PassportDate>andpassportDateOf()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 newCREDITS.md, organised by three tests: upstream maintainers who fixed what we reported (xml-sec, the EUDI SD-JWT library), the reference implementationsdpp-coreis 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
.envfiles in the diff