https://github.com/0101011/doc-n-code

https://github.com/0101011/doc-n-code

documentation technical-writing writing

Last synced: 7 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/0101011/doc-n-code
• Owner: 0101011
• Created: 2024-05-12T22:24:10.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-05-14T18:16:15.000Z (about 2 years ago)
• Last Synced: 2025-01-04T18:12:13.409Z (over 1 year ago)
• Topics: documentation, technical-writing, writing
• Homepage:
• Size: 4.88 KB
• Stars: 17
• Watchers: 4
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
## 10 Fast Rules for Documenting Software

1. **Write Comments as You Code**

   - Comments are crucial for understanding code later

   - Write comments as you code to capture your thought process

   - Aim for a balanced amount of comments, not too few or too many

```python

# Bad (no comments)

for sequence in parsed_sequences: 

    analyze(sequence)

# Bad (too many comments)  

# iterate over the genes in the genome

for sequence in parsed_sequences:

    # call the analyze function, passing it each gene as argument

    analyze(sequence) 

# Good (just enough)

# Analyze the genome 

for sequence in parsed_sequences:

    analyze(sequence)

```

2. **Include Examples (and Lots of Them)**

   - Examples provide a starting point for experimentation

   - Include examples demonstrating key functionality  

   - Examples can also serve as unit tests

3. **Include a Quickstart Guide**

   - Help users get started with your software quickly

   - Use examples, tutorials, videos, or other formats

   - Test your quickstart guide to ensure it's effective

4. **Include a README File with Basic Information**

   - The README acts as the homepage for your project

   - Include installation, configuration, documentation links, license, testing, and acknowledgments

   - Consider using badges to show project status

5. **Include a Help Command for Command Line Interfaces**

   - Document how to use your CLI with a "help" command

   - Include usage, subcommands, options/arguments, environment variables, and examples

   - Use tools like click (Python) to generate the help command

6. **Version Control Your Documentation**  

   - Keep documentation in your version control repository

   - Archive rendered documentation for each release

   - Provide a changelog to track changes between versions

7. **Fully Document Your Application Programming Interface (API)** 

   - Document inputs, outputs, errors, methods, and attributes

   - Follow a consistent style guide for API documentation

8. **Use Automated Documentation Tools**

   - Tools like Sphinx, Doxygen, and MkDocs can generate documentation

   - Automate API documentation, interactive REST API docs, and more

   - Use services like Read the Docs to keep documentation up-to-date  

9. **Write Error Messages that Provide Solutions or Point to Documentation**

   - Good error messages state the error, software state, and how to fix it

   - Provide guidance in error messages to save users' time

```python

# Bad

print("Error: Translation failed.")

# Good  

print("Error: Translation failed because of an invalid codon (\"IQT\") "

      "in position 1 in sequence 41. Ensure this is a valid DNA "

      "sequence and not a protein sequence.")

```

10. **Tell People How to Cite Your Software**

    - Include DOI, BibTeX entry, and written reference in the README

    - Use a CITATION file in Citation File Format (CFF)

    - Get a DOI for your software from services like Zenodo or JOSS

## Additional Tips

- **Use Consistent Formatting**

    - Use a consistent style for headers, code blocks, etc.

    - Markdown allows for consistent formatting across platforms

```markdown

### Header 3

#### Header 4

`inline code`

```python

# Code block

print("Hello World!")

```

- **Structure Documentation Well**

    - Break documentation into logical sections and chapters

    - Use tables of contents and cross-references where appropriate

- **Include Visual Aids**

    - Use diagrams, flowcharts, and screenshots to clarify concepts

    - Reference images using relative paths

- **Make Documentation Searchable**

    - Use proper headings and anchor links

    - Consider using a search plugin for websites

- **Keep Documentation Up-to-Date**

    - Automate documentation updates when code changes

    - Encourage contributors to update documentation