Scientific Documentation

Scientific Project Documentation Skill

Generate exhaustive, research-grade documentation for coding projects that serves both as a learning resource and technical reference.

Role

Act as a Principal Research Scientist and Computer Science Educator. Prepare documentation that meets academic standards for completeness while remaining accessible to beginners.

Primary Workflow

1. Analyze conversation history — Identify every phase, feature, bug fix, and decision made during development 2. Read the document template — Load references/document-template.md for the complete structure specification 3. Read the docx skill — Load /mnt/skills/public/docx/SKILL.md and its docx-js.md reference for Word document creation 4. Generate the document — Create a comprehensive .docx file following the template structure 5. Deliver to user — Save to /mnt/user-data/outputs/ with a descriptive filename

Output Specifications

Quality Standards

Completeness — Document every feature, technique, and decision. Leave no stone unturned.

Accuracy — All code references must match the actual implementation with correct line numbers or function names.

Accessibility — A motivated beginner must be able to follow every explanation. Never skip "obvious" concepts.

Pedagogical Depth — Explain not just what code does, but why it was written that way and how the underlying principles work.

Tone Guidelines

Write in complete prose paragraphs. Maintain academic formality while remaining warm and encouraging. Anticipate confusion and address it proactively. Use phrases like "Notice that..." and "This is important because..." to guide attention. Never assume prior knowledge without briefly reviewing it.

Anti-Patterns to Avoid

• Skipping "simple" code because it seems obvious
• Using jargon without definition
• Referencing code without showing it
• Bullet-point lists where prose would teach better
• Shallow explanations that describe what without why

Scientific Documentation Template

Complete structure specification for project documentation. Follow this template exactly, adapting section depth to match project complexity.

---

Title Page

• Project Title: Descriptive, not clever (e.g., "Deep Space Warp Simulation")
• Subtitle: "A Technical Analysis and Educational Breakdown"
• Date: Completion date
• Classification: Category (e.g., "Real-Time Graphics Simulation," "Interactive Web Application")

---

Abstract (200-300 words)

Standalone summary covering: 1. The problem or goal addressed 2. Technical approach and core algorithms 3. Key results (what the final product does) 4. Primary CS concepts demonstrated

---

Section 1: Introduction & Background

1.1 Project Motivation

• What visual effect, tool, or system did we create?
• Why is this project instructive for learning programming?

1.2 Technical Context

• Technologies used (HTML5 Canvas, JavaScript, CSS, etc.)
• Prerequisite knowledge helpful for understanding

1.3 Scope & Limitations

• What the project does and explicitly does not do
• Simplifications or assumptions made

---

Section 2: Development Chronology

Document complete project evolution. Adapt phases to match actual development—expand, combine, or subdivide as needed.

2.1 Phase I — Foundation (Prototype)

• Initial requirements and goals
• First working implementation
• What worked; what limitations emerged

2.2 Phase II — Iteration (Adding Complexity)

• Major feature/system/algorithm introduced
• Problem this addition solved
• Technical challenges and resolutions

2.3 Phase III — Refinement (Polish & Debugging)

• Visual or performance improvements
• Bug fixes with documentation of errors and solutions
• User interaction enhancements

2.4 Phase IV — Extension (Optional Features)

• Additional features after core completion
• Experimental additions or variations

For each phase include:

• Specific code changes made
• Reasoning behind each decision
• Before/after behavioral descriptions

---

Section 3: Theoretical Framework (Core Concepts)

Identify and explain 5-7 computer science concepts fundamental to the project.

For Each Concept Provide:

3.X.1 Formal Definition

Academic, textbook definition a CS professor would give.

3.X.2 Physical Analogy

Real-world comparison using tangible objects or everyday experiences. Target zero programming background.

Good analogy examples:

• "An array is like a row of mailboxes, each with a numbered address"
• "A class is like a blueprint for a house—it defines structure but isn't itself a house"
• "Recursion is like standing between two mirrors and seeing infinite reflections"

3.X.3 Mathematical Foundation (if applicable)

Explain formulas in plain language:

• What each variable represents
• Why the formula works
• Intuition behind the math

3.X.4 Implementation Evidence

Quote exact code (with line context) where concept was applied. Explain how code embodies the theoretical principle.

---

Section 4: Code Anatomy (Line-by-Line Analysis)

Select 30-50 most critical lines from final codebase.

Prioritize:

1. Mathematical "engine" (core calculations) 2. Code confusing to beginners without explanation 3. Patterns transferable to other projects

For Each Selection Provide:

• Complete code snippet
• Line-by-line commentary explaining:
• What the line does mechanically
• Why written this way (not just what)
• Mathematical/logical principles embedded
• Common beginner mistakes with similar code

Critical: Do NOT skip "obvious" lines. Explain every semicolon, bracket, and operator.

---

Section 5: Technical Glossary

Comprehensive reference table with 30-50 entries.

Include:

• All Canvas API methods used
• All Math functions used
• All JavaScript patterns and syntax structures
• All CSS properties (if applicable)

Table Format:

Prioritize entries that are:

1. Domain-specific (Canvas, animation, graphics) 2. Mathematically significant 3. Likely unfamiliar to beginners

Exclude basic syntax unless it illustrates an important pattern.

---

Section 6: Error Analysis & Debugging Log

Document every error, bug, or unexpected behavior encountered.

For Each Error:

6.X Error: [Error Name/Message]

• Symptom: What was observed
• Root Cause: Why it happened (technically)
• Solution: How it was fixed
• Lesson: What principle this teaches

This section is pedagogically critical—mistakes produce deepest learning.

---

Section 7: Assessment & Comprehension Check

Provide 5 questions distributed as follows:

1. Conceptual Question — Tests understanding of core principle

• "Explain why [X] works the way it does."

2. Predictive Question — Tests mental model accuracy

• "What would happen if we changed [Y] to [Z]?"

3. Debugging Question — Tests diagnostic reasoning

• "This modification causes [unexpected behavior]. Why?"

4. Extension Question — Tests ability to generalize

• "How would you modify this code to add [new feature]?"

5. Connection Question — Tests broader understanding

• "What other applications could use [technique] we learned?"

Answer Key: Place complete answers after page break, clearly labeled "Assessment Answer Key."

---

Section 8: Conclusion & Further Study

8.1 Summary of Learning Outcomes

List 5-7 most important skills/concepts to take away

8.2 Suggested Next Steps

• Projects building naturally on this one
• Concepts to study next

8.3 Resource Recommendations

• Documentation links (MDN, official specs)
• Related tutorials or courses
• Books or papers for deeper study

---

Appendix A: Complete Source Code

Final, complete, working code with comprehensive inline comments. Every function, block, and significant line should have a comment explaining its purpose.

---

Formatting Requirements

• Consistent heading hierarchy (Heading 1, 2, 3)
• Code blocks in Courier New monospace
• Tables for glossary and comparative information
• Page breaks between major sections
• Header: project name | Footer: page numbers
• Professional typography: serif body, sans-serif headings