NIP 3 - Documenting a new feature
NIP: 3 Title: Documenting a new feature Author: David Garcia <firstname.lastname@example.org> Discussions-To: #sig-docs Comments-URI: https://github.com/nemtech/NIP/issues/9 Status: Draft Type: Process Created: 2019-01-23 License: BSD-2-Clause
Table of contents
This NIP introduces a detailed process to document a new feature.
- Define collaboration between different SIG regarding docs.
- Include documentation in the definition of done.
- Enable docs collaboration in the different stages.
- Increase the availability of new information related to development.
Features: Features are treated as single entities, independently of the milestone they belong. This allows merging changes without waiting for other features pending to be finished.
Phases: As we are collaborating between different parties in a remote setup, it is necessary to share materials once ready in different moments. As a general rule, don’t pre-announce in master a feature that has not been released in at least the catapult-server repository.
|Specification||Accepted NIP (NIP author)||Create a new branch in nem2-docs repository using the NIP’s identifier.|
|Feature is available in catapult-server||Server Deliverables (SIG-Server) and Concept (SIG-docs)||a) Publish concept(*).
b) Merge to master.
Translations can start.
|Feature becomes testable||Endpoints (SIG-api) and Swagger (SIG-docs)||a) Publish updated swagger file.
b) Publish the list of required guides as open Github issues in nem2-docs repository.
|Feature becomes usable||SDK comments (SIG-api), SDK reference (SIG-docs) and Guides (SIG-docs + community)||a) Publish SDK docs.
(*) If the feature is not testable or usable, e.g. SDK is not usable but REST is advanced, this should be remarked in the documentation. Once the feature reaches the master branch, it can be promoted by the different stakeholders as a newly included feature.
Participants: Each group should provide the required documentation in the specified format (see Annex: Deliverables). Keeping the nem-docs repository updated and supervise the documentation process is the responsibility of the SIG-doc.
Revision: At least two different people form the SIG-docs should review the changes before the committer merges them to master.
|Accepted NIP||Document describing specification and the design decisions for a new NEM feature. Note: Accepted NIPS require to be publicly available after RC release.||NIP Structure The specification may have as annex some behavior scenarios to drive the development.|
|Concept||The specification formatted for documentation.||Feature explanation, Examples and schemas.|
|Server Deliverables||The required pieces of documentation around the server changes.||Changelog (published in the catapult-server repository), Status Errors (Result.h validators), Entity Schemas and configuration changes.|
|Endpoints||The list of additions/modifications in catapult-rest.||Endpoint urls, methods, parameters, and example responses.|
|Swagger||The additions / modifications in catapult-rest formatted.||Swagger file|
|SDK comments||The SDK classes and methods should be described in the code.||Comments format|
|SDK reference||The SDK generated reference.||Generated reference|
|Guides||Articles explaining how to use the new feature step by step. Each article can include recommendations, best practices, and combination with other features.||Writing a guide|
|Jan 23 2018||Initial Draft|