Skip to main content

How to write documents

Why documents are important​

As a developer, it's always important to have reliable documentation to guide your work. If you are like most developers, you can be supporting multiple applications at the same time, which means that it is even more crucial to have documentation in place to help track all aspects of each application. It's also helpful for development, maintenance, and knowledge transfer to other developers.

How to write the documents​

tip

Document files are written by Markdown.

Rules​

Create Github repository based on tutorial here for each Independent specific data cohort with related model codes.

info

The maintainer of Github repository is responsible to update README.md routinely.
Admin group will check the documents from time to time, documents should be updated no later than 10 days once Github gets updated.

What should be included​

  • Description of the data or codes:

    • What is the code or data used for ?
    • What is the architecture of the repository ?
      • Explain the folder architecture and each module's usage
    • What is the workflow of the repository ? Flowchart
    • What is the status of development ? (New / In Progress / Complete)
    • Who should be contacted with ?

  • Requirements for the data or codes:

    • Are there any dependent datasets ?
    • Are there any dependent packages or frameworks ?
    • Is there any required processing environment (Python / R / Scala)?
  • Operations of the data or codes with example commands:
    • How to run the codes ?
    • How to update or make changes to the data or codes ?
  • Deployment of the service or codes with example commands [DevOps]:
    • Where will the service or codes be deployed ?
    • How to create the docker container to deploy the service ?
    • Are there any resources limitations for the service or the codes ?
    • Are there any monitoring modules for the service or the codes ?
    • How to process the accidental cases ?

What is the difference between this online document and Github repository​

  • This document is going to provide the general information for various projects, data resources and applications. Github documents should be more detailed and executable for specific task.