└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | ## 10 Fast Rules for Documenting Software
  2 | 
  3 | 1. **Write Comments as You Code**
  4 |    - Comments are crucial for understanding code later
  5 |    - Write comments as you code to capture your thought process
  6 |    - Aim for a balanced amount of comments, not too few or too many
  7 | 
  8 | ```python
  9 | # Bad (no comments)
 10 | for sequence in parsed_sequences: 
 11 |     analyze(sequence)
 12 | 
 13 | # Bad (too many comments)  
 14 | # iterate over the genes in the genome
 15 | for sequence in parsed_sequences:
 16 |     # call the analyze function, passing it each gene as argument
 17 |     analyze(sequence) 
 18 | 
 19 | # Good (just enough)
 20 | # Analyze the genome 
 21 | for sequence in parsed_sequences:
 22 |     analyze(sequence)
 23 | ```
 24 | 
 25 | 2. **Include Examples (and Lots of Them)**
 26 |    - Examples provide a starting point for experimentation
 27 |    - Include examples demonstrating key functionality  
 28 |    - Examples can also serve as unit tests
 29 | 
 30 | 3. **Include a Quickstart Guide**
 31 |    - Help users get started with your software quickly
 32 |    - Use examples, tutorials, videos, or other formats
 33 |    - Test your quickstart guide to ensure it's effective
 34 | 
 35 | 4. **Include a README File with Basic Information**
 36 |    - The README acts as the homepage for your project
 37 |    - Include installation, configuration, documentation links, license, testing, and acknowledgments
 38 |    - Consider using badges to show project status
 39 | 
 40 | 5. **Include a Help Command for Command Line Interfaces**
 41 |    - Document how to use your CLI with a "help" command
 42 |    - Include usage, subcommands, options/arguments, environment variables, and examples
 43 |    - Use tools like click (Python) to generate the help command
 44 | 
 45 | 6. **Version Control Your Documentation**  
 46 |    - Keep documentation in your version control repository
 47 |    - Archive rendered documentation for each release
 48 |    - Provide a changelog to track changes between versions
 49 | 
 50 | 7. **Fully Document Your Application Programming Interface (API)** 
 51 |    - Document inputs, outputs, errors, methods, and attributes
 52 |    - Follow a consistent style guide for API documentation
 53 | 
 54 | 8. **Use Automated Documentation Tools**
 55 |    - Tools like Sphinx, Doxygen, and MkDocs can generate documentation
 56 |    - Automate API documentation, interactive REST API docs, and more
 57 |    - Use services like Read the Docs to keep documentation up-to-date  
 58 | 
 59 | 9. **Write Error Messages that Provide Solutions or Point to Documentation**
 60 |    - Good error messages state the error, software state, and how to fix it
 61 |    - Provide guidance in error messages to save users' time
 62 | 
 63 | ```python
 64 | # Bad
 65 | print("Error: Translation failed.")
 66 | 
 67 | # Good  
 68 | print("Error: Translation failed because of an invalid codon (\"IQT\") "
 69 |       "in position 1 in sequence 41. Ensure this is a valid DNA "
 70 |       "sequence and not a protein sequence.")
 71 | ```
 72 | 
 73 | 10. **Tell People How to Cite Your Software**
 74 |     - Include DOI, BibTeX entry, and written reference in the README
 75 |     - Use a CITATION file in Citation File Format (CFF)
 76 |     - Get a DOI for your software from services like Zenodo or JOSS
 77 | 
 78 | ## Additional Tips
 79 | 
 80 | - **Use Consistent Formatting**
 81 |     - Use a consistent style for headers, code blocks, etc.
 82 |     - Markdown allows for consistent formatting across platforms
 83 | 
 84 | ```markdown
 85 | ### Header 3
 86 | 
 87 | #### Header 4
 88 | 
 89 | `inline code`
 90 | 
 91 | ```python
 92 | # Code block
 93 | print("Hello World!")
 94 | ```
 95 | 
 96 | - **Structure Documentation Well**
 97 |     - Break documentation into logical sections and chapters
 98 |     - Use tables of contents and cross-references where appropriate
 99 | 
100 | - **Include Visual Aids**
101 |     - Use diagrams, flowcharts, and screenshots to clarify concepts
102 |     - Reference images using relative paths
103 | 
104 | - **Make Documentation Searchable**
105 |     - Use proper headings and anchor links
106 |     - Consider using a search plugin for websites
107 | 
108 | - **Keep Documentation Up-to-Date**
109 |     - Automate documentation updates when code changes
110 |     - Encourage contributors to update documentation
111 | 


--------------------------------------------------------------------------------