Write down docs styleguide

[martriay]

No description provided.

[martriay]

• avoid talking about "us", or the writer as much as possible
• don’t capitalize Account unless it’s a specific contract/impl

[ericnordelo]

• Don't include argument types in the header sections for Utilities, Functions, and Events, in the API Reference.

[andrew-fleming]

• Write the casing name in the casing style e.g. camelCase, snake_case, PascalCase, etc

[andrew-fleming]

• Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)

  • For the record, I disagree with this approach. I instead vote for title case in all doc headings because:
    1. Titles of sections are, well, titles and titles should be capitalized IMO.
    2. Consistency with OZ Solidity docs.

[martriay]

Use "panics" instead of "reverts" or "throws" since it's the appropriate term in Starknet.

[martriay]

Add / at the end of directory names to highlight it's a directory. e.g.: my_folder/ instead of my_folder

[ericnordelo]

Always scope IDs by the module name in API Reference. Under the ERC20 module section, the name() function should have the ID: ERC20-name

[ericnordelo]

Words in html IDs (adoc pages) must be separated by dashes: ERC20-name instead of ERC20::name

[martriay]

Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)

• For the record, I disagree with this approach. I instead vote for title case in all doc headings because:

  1. Titles of sections are, well, titles and titles should be capitalized IMO.
  2. Consistency with OZ Solidity docs.

where does this rule come from, if you disagree with it?

Always scope IDs by the module name in API Reference. Under the ERC20 module section, the name() function should have the ID: ERC20-name

what do you mean by scope IDs? is this an ascii doc thing?

[andrew-fleming]

Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)

• For the record, I disagree with this approach. I instead vote for title case in all doc headings because:

• Titles of sections are, well, titles and titles should be capitalized IMO.
• Consistency with OZ Solidity docs.

where does this rule come from, if you disagree with it?

It's just how the old and forthcoming docs are currently written. There's no rule that I'm aware of

[ericnordelo]

what do you mean by scope IDs? is this an ascii doc thing?

The ID of the HTML section generated from the adoc file, should be scoped by the module name: have this #Account-supports_interface, instead of just #supports_interface.

[.contract-item]
[[Account-supports_interface]]
...

[ericnordelo]

Put SRC5 ID block as a section (similar to Functions and Events) on top at the Interfaces where the ID is usually exposed.

[martriay]

to do: resolve whether we include return values in API definitions

[martriay]

Opened the "Consider documenting asserts/guards" discussion separately in its own thread: #745

[martriay]

to do: decide what to do regarding duplicating function definitions between interface, component, and function definitions in API docs: see discussions #1, #2, and #3

[andrew-fleming]

Closing this issue as this is done internally.