{"id":19214255,"url":"https://github.com/0101011/doc-n-code","last_synced_at":"2025-11-13T17:04:36.235Z","repository":{"id":239807213,"uuid":"799696129","full_name":"0101011/doc-n-code","owner":"0101011","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-14T18:16:15.000Z","size":5,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-04T18:12:13.409Z","etag":null,"topics":["documentation","technical-writing","writing"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0101011.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-12T22:24:10.000Z","updated_at":"2024-07-14T15:10:03.000Z","dependencies_parsed_at":"2024-05-15T14:43:01.689Z","dependency_job_id":"c8f37662-eb94-49fb-a08b-4c7529ca4be1","html_url":"https://github.com/0101011/doc-n-code","commit_stats":null,"previous_names":["0101011/doc-n-code"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0101011%2Fdoc-n-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0101011%2Fdoc-n-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0101011%2Fdoc-n-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0101011%2Fdoc-n-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0101011","download_url":"https://codeload.github.com/0101011/doc-n-code/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240287643,"owners_count":19777517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","technical-writing","writing"],"created_at":"2024-11-09T14:09:30.823Z","updated_at":"2025-11-13T17:04:31.193Z","avatar_url":"https://github.com/0101011.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## 10 Fast Rules for Documenting Software\n\n1. **Write Comments as You Code**\n   - Comments are crucial for understanding code later\n   - Write comments as you code to capture your thought process\n   - Aim for a balanced amount of comments, not too few or too many\n\n```python\n# Bad (no comments)\nfor sequence in parsed_sequences: \n    analyze(sequence)\n\n# Bad (too many comments)  \n# iterate over the genes in the genome\nfor sequence in parsed_sequences:\n    # call the analyze function, passing it each gene as argument\n    analyze(sequence) \n\n# Good (just enough)\n# Analyze the genome \nfor sequence in parsed_sequences:\n    analyze(sequence)\n```\n\n2. **Include Examples (and Lots of Them)**\n   - Examples provide a starting point for experimentation\n   - Include examples demonstrating key functionality  \n   - Examples can also serve as unit tests\n\n3. **Include a Quickstart Guide**\n   - Help users get started with your software quickly\n   - Use examples, tutorials, videos, or other formats\n   - Test your quickstart guide to ensure it's effective\n\n4. **Include a README File with Basic Information**\n   - The README acts as the homepage for your project\n   - Include installation, configuration, documentation links, license, testing, and acknowledgments\n   - Consider using badges to show project status\n\n5. **Include a Help Command for Command Line Interfaces**\n   - Document how to use your CLI with a \"help\" command\n   - Include usage, subcommands, options/arguments, environment variables, and examples\n   - Use tools like click (Python) to generate the help command\n\n6. **Version Control Your Documentation**  \n   - Keep documentation in your version control repository\n   - Archive rendered documentation for each release\n   - Provide a changelog to track changes between versions\n\n7. **Fully Document Your Application Programming Interface (API)** \n   - Document inputs, outputs, errors, methods, and attributes\n   - Follow a consistent style guide for API documentation\n\n8. **Use Automated Documentation Tools**\n   - Tools like Sphinx, Doxygen, and MkDocs can generate documentation\n   - Automate API documentation, interactive REST API docs, and more\n   - Use services like Read the Docs to keep documentation up-to-date  \n\n9. **Write Error Messages that Provide Solutions or Point to Documentation**\n   - Good error messages state the error, software state, and how to fix it\n   - Provide guidance in error messages to save users' time\n\n```python\n# Bad\nprint(\"Error: Translation failed.\")\n\n# Good  \nprint(\"Error: Translation failed because of an invalid codon (\\\"IQT\\\") \"\n      \"in position 1 in sequence 41. Ensure this is a valid DNA \"\n      \"sequence and not a protein sequence.\")\n```\n\n10. **Tell People How to Cite Your Software**\n    - Include DOI, BibTeX entry, and written reference in the README\n    - Use a CITATION file in Citation File Format (CFF)\n    - Get a DOI for your software from services like Zenodo or JOSS\n\n## Additional Tips\n\n- **Use Consistent Formatting**\n    - Use a consistent style for headers, code blocks, etc.\n    - Markdown allows for consistent formatting across platforms\n\n```markdown\n### Header 3\n\n#### Header 4\n\n`inline code`\n\n```python\n# Code block\nprint(\"Hello World!\")\n```\n\n- **Structure Documentation Well**\n    - Break documentation into logical sections and chapters\n    - Use tables of contents and cross-references where appropriate\n\n- **Include Visual Aids**\n    - Use diagrams, flowcharts, and screenshots to clarify concepts\n    - Reference images using relative paths\n\n- **Make Documentation Searchable**\n    - Use proper headings and anchor links\n    - Consider using a search plugin for websites\n\n- **Keep Documentation Up-to-Date**\n    - Automate documentation updates when code changes\n    - Encourage contributors to update documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0101011%2Fdoc-n-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0101011%2Fdoc-n-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0101011%2Fdoc-n-code/lists"}