Documentation refresh - Atlanta workshop (rebased)

.github/ISSUE_TEMPLATE/documentation-task.yml

@@ -0,0 +1,92 @@
+name: Documentation task
+description: File a scoped issue for documentation changes in Macaulay2.
+title: "docs: "
+labels:
+  - documentation
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Documentation area
+      description: Choose the main area affected by this issue.
+      options:
+        - Build and install docs
+        - Internal/reference docs
+        - Package docs
+        - Tutorials and examples
+        - Editor/tooling docs
+        - Contributor guidance
+        - Repository-wide cleanup
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: State the problem in one short paragraph.
+      placeholder: What is wrong, unclear, outdated, or missing?
+    validations:
+      required: true
+
+  - type: textarea
+    id: paths
+    attributes:
+      label: Affected paths
+      description: List the files or directories likely to change.
+      placeholder: |
+        README.md
+        M2/Macaulay2/docs/index.rst
+        M2/Macaulay2/packages/SomePackage/README.md
+    validations:
+      required: true
+
+  - type: textarea
+    id: desired_outcome
+    attributes:
+      label: Desired outcome
+      description: Describe what "done" looks like for this task.
+      placeholder: After this issue is complete, what should a reader be able to do or understand?
+    validations:
+      required: true
+
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification
+      description: Say how the updated docs should be checked.
+      placeholder: |
+        Example:
+        - Rerun the commands in the README
+        - Check links
+        - Build the relevant docs, if applicable
+    validations:
+      required: true
+
+  - type: dropdown
+    id: size
+    attributes:
+      label: Estimated size
+      options:
+        - Small
+        - Medium
+        - Large
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: review_flags
+    attributes:
+      label: Review flags
+      options:
+        - label: This issue needs mathematical review.
+        - label: This issue needs examples or commands to be rerun.
+        - label: This issue may require follow-up issues instead of one PR.
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies or blockers
+      description: Note related issues, required decisions, or blockers.
+      placeholder: Optional

.github/pull_request_template.md

@@ -1,5 +1,18 @@
-<!--
-Thank you for contributing to Macaulay2!
+## Summary
 
-Please read https://github.com/Macaulay2/M2/wiki/Pull-requests for instructions.
--->
+Describe the documentation change and the main files it touches.
+
+## Related Issue
+
+Link the issue in `Macaulay2/M2` or `aalmousa/M2` that this PR addresses.
+
+## Verification
+
+List what you checked locally. Be explicit about examples, links, generated
+html, or any verification you could not complete.
+
+## Notes
+
+- Keep the scope focused. Split unrelated documentation work into separate PRs.
+- See `README.md` and the Macaulay2 wiki for the current contribution
+  workflow.

M2/BUILD/README.md

@@ -1,5 +1,6 @@
-See [INSTALL](../INSTALL) or [INSTALL-CMake.md](../INSTALL-CMake.md) for build
-requirements and instructions.
+See the [Macaulay2 wiki](https://github.com/Macaulay2/M2/wiki) for current
+build requirements and instructions, especially the "Building M2 from source"
+pages for the autotools and CMake workflows.
 
 This directory may be used as a convenient location for the build directory
 trees.  For example, it may contain subdirectories `Linux-i686` and
@@ -33,5 +34,5 @@ architecture-independent files are in a subdirectory of this directory called
 `common`, and the architecture-dependent files will be in other subdirectories,
 such as `x86_64-Linux-Ubuntu-8.10`.  (Actually, this is being changed...)
 
-Alternatively, see the [this guide](docker/README.md) for instructions on using
-Docker to build Linux container images running Macaulay2.
+Alternatively, see the [Docker guide](docker/README.md) for instructions on
+using Docker to build Linux container images running Macaulay2.