SRML Documentation Template

[shawntabrizi]

We need to create a markdown template for SRML documentation

MUST: Include all of these sections/subsections

Overview

• short description of module purpose
• links to [Traits], [Call], [Module]

standard format (example):

The timestamp module provides functionality to get and set the on-chain time.

See also: [Trait] [Call] [Module]

Interface

Dispatchable

MUST: Have link to Call enum
MUST: Have origin information included in function doc
CAN: Have more info up to the user

Public

up to writer for respective module (wrt how much information to provide)

Usage

Prerequisites

necessary imports

Simple Code Snippet

Example from SRML

Genesis Config

Related Modules

bulleted list to other modules (maybe one sentence)

References

[shawntabrizi]

@gautamdhameja How does something like this sound:

• Introduction
  • The purpose of the module as 1-2 paragraphs
• How to use
  • Explain how users (or system processes) use and interact with this module
  • Common call patterns
• Core Logic and Assumptions
  • Basically talk about implementation details that look important or distinguish our module
  • These might be details that the user can modify or customize to make their own
• Interactions with other SRML
• Links to other associated module documentation pages

[kianenigma]

^^ Looks pretty close to what I had in mind. Will go with this for now. If you throw in here an example of of @gautamdhameja 's docs with this structure, it will be also helpful.

[gautamdhameja]

@shawntabrizi yes, something on the same lines but a bit more detailed (so that all module docs have a similar structure). Here's what I think.

Module name

// Simple description

Overview

// description
// what this module is for
// what it provides
// when to use it - use case examples

Public Interface

// what are the public functions exposed by this module and for each function we should have,
// description of function - what it does
// signature - input params
// events
// errors

Usage

// examples, code snippets for module usage

Implementation details

// implementation details that look important or distinguish our module

Extensibility

// Details that the user can modify or customize to make their own

Dependencies

// Dependencies on other SRML modules
// Genesis config
// Interaction with other modules

Further information

// links to other docs, relevant GitHub issues and other information

[shawntabrizi]

@gautamdhameja I like it a lot. The harder question I have is what we talked about regarding splitting docs between Rust Docs and written stuff.

Things like public interface and usage seem like things that should live in the rust docs. Question would be "Can we automagically get/generate this data so that it is seamless/easy to keep things in sync?"

Furthermore how can we ensure that users know to look in the rust docs for this kind of details?

Furthermore how do we make sure stuff is searchable and discoverable?

[gautamdhameja]

I had the exact same question in mind. I agree that the public interface and usage should live with the code in Rust docs. @ltfschoen also suggested the same.
We can either embed the static html produced by rustdoc or we can link to where it will be hosted (crates.parity.io, I guess). I would prefer linking.
https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html

[shawntabrizi]

Yeah, but maybe also we can try and automate some copy and paste blob that is generated from the rust docs such that we can also have some amount of content on the markdown page so it is searchable from the main readme site

[gautamdhameja]

Sure, we can. But I'd say let's focus on the content creation for now. We can have some automation tools/scripts later to improve the content presentation.

[kianenigma]

I'm definitely in favor of not having a full (or even partial) list of public functions in an .md doc. This will be a pure duplicate and makes the page look much longer.

What I've been doing so far for one of the docs is to have the overview section explain verbally some of the common scenarios that can happen withing and using the module, and I'm planning to bombard it as much as possible with links to associated rustdoc functions.