From a573c05f171ec7e8a39544adb4b7f6995e55242e Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Thu, 23 Feb 2023 11:30:15 -0800 Subject: [PATCH 1/6] Create project_documentation.md --- ptc_cards/project_documentation.md | 41 ++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 ptc_cards/project_documentation.md diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md new file mode 100644 index 00000000..4b449480 --- /dev/null +++ b/ptc_cards/project_documentation.md @@ -0,0 +1,41 @@ +[metadata:tags]:- "bssw-psip-ptc" +# Structured Project Documentation + + Download this PTC (Markdown) + +## Target + +Improve our team’s project documentation. This includes code documentation and user documentation. + +## Approach + +Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. + + +## User Story + +* **As a** developer, **I want** to document my code, **so that** it is easy understand and potentially change. +* **As a** user of the software, **I want** to know what functionality is available to me and how to use it. + + +## Card(s) + +| Stage | Description | +| :-------------: | :------------- | +| 0 | Team does ad-hoc code documentation. Up to each developer to decide what code to document (possibly none) and how to document. At best, inline comments are scattered through code. User manuals, if they exist, are hand-created.| +| 1 | Team has a vague mandate to document well. What and how remain ad hoc. User manuals are hand-created.| +| 2 | Team chooses a modern structured-documentation tool, e.g., Doxygen. Developers are required to use Doxygen comments for every major component in their code, e.g., functions, subroutines, structs, classes. Structure of comments remains loose. User manuals are now automatically built from code comments. 1| +| 3 | Team uses the often full-featured structuring features of a tool, e.g., Doxygen. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become more useful. 2| +| 4 | Team relies on the PR process to incrementally fill in fields. PR reviewers check for missing field content and ask PR author to fill in.| +| 5 | Team uses MeerCat to check for placeholders indicating missing content, relieving the reviewer of this task. MeerCat can find fields with missing content and help the developer (PR author) fill them in.| +| 6 | Eventually, fully-realized structured-documentation is produced and a rich user manual is generated.| + + +## Comments +1. Using tool support to start the transition to structured-documentation is often feasible. For instance, formatted documentation templates can be inserted at appropriate locations with placeholders for actual content for a developer to fill in. +2. Again, tool support to generate the required fields is often possible, leaving the actual content of the field for the developer to fill in. + + +### Acknowledgement + +This Project Tracking Card originated from the [PSIP PTC Catalog](https://bssw-psip.github.io/ptc-catalog/). The development of the PSIP PTC Catalog was supported by the Exascale Computing Project (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy Office of Science and the National Nuclear Security Administration. From 8b3081a7e25ee38a38f43274d0ab07398274f729 Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Thu, 23 Feb 2023 11:34:35 -0800 Subject: [PATCH 2/6] Update project_documentation.md --- ptc_cards/project_documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md index 4b449480..88cdae78 100644 --- a/ptc_cards/project_documentation.md +++ b/ptc_cards/project_documentation.md @@ -28,7 +28,7 @@ Use documentation structuring tools (e.g., Doxygen) that take structured code do | 3 | Team uses the often full-featured structuring features of a tool, e.g., Doxygen. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become more useful. 2| | 4 | Team relies on the PR process to incrementally fill in fields. PR reviewers check for missing field content and ask PR author to fill in.| | 5 | Team uses MeerCat to check for placeholders indicating missing content, relieving the reviewer of this task. MeerCat can find fields with missing content and help the developer (PR author) fill them in.| -| 6 | Eventually, fully-realized structured-documentation is produced and a rich user manual is generated.| +| 6 | Eventually, fully-realized structured-documentation is produced and a rich user manual is generated. A win for both developers and users.| ## Comments From aab8939a46f410511db8732c87778c1188b64377 Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Thu, 23 Feb 2023 15:59:43 -0800 Subject: [PATCH 3/6] Update project_documentation.md Revision after meeting 2/23/23. --- ptc_cards/project_documentation.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md index 88cdae78..52f5b13d 100644 --- a/ptc_cards/project_documentation.md +++ b/ptc_cards/project_documentation.md @@ -1,39 +1,38 @@ [metadata:tags]:- "bssw-psip-ptc" -# Structured Project Documentation +# Structured Project Documentation with MeerCat support Download this PTC (Markdown) ## Target -Improve our team’s project documentation. This includes code documentation and user documentation. +Improve our team’s project documentation. This includes code documentation and user documentation. Lessen burden on code reviewers to hunt for missing documentation. ## Approach -Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. +Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. Use MeerCat to find missing documentation and to create it. ## User Story * **As a** developer, **I want** to document my code, **so that** it is easy understand and potentially change. -* **As a** user of the software, **I want** to know what functionality is available to me and how to use it. +* **As a** user of the software, **I want** to know what functionality is available to me and how to use it. +* **As a** code reviewer (a Pull-Request reviewer), **I want** to avoid the tedium of searching through files looking for missing documentation. ## Card(s) | Stage | Description | | :-------------: | :------------- | -| 0 | Team does ad-hoc code documentation. Up to each developer to decide what code to document (possibly none) and how to document. At best, inline comments are scattered through code. User manuals, if they exist, are hand-created.| -| 1 | Team has a vague mandate to document well. What and how remain ad hoc. User manuals are hand-created.| -| 2 | Team chooses a modern structured-documentation tool, e.g., Doxygen. Developers are required to use Doxygen comments for every major component in their code, e.g., functions, subroutines, structs, classes. Structure of comments remains loose. User manuals are now automatically built from code comments. 1| -| 3 | Team uses the often full-featured structuring features of a tool, e.g., Doxygen. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become more useful. 2| -| 4 | Team relies on the PR process to incrementally fill in fields. PR reviewers check for missing field content and ask PR author to fill in.| -| 5 | Team uses MeerCat to check for placeholders indicating missing content, relieving the reviewer of this task. MeerCat can find fields with missing content and help the developer (PR author) fill them in.| -| 6 | Eventually, fully-realized structured-documentation is produced and a rich user manual is generated. A win for both developers and users.| +| 0 | Team does ad-hoc code documentation, possibly with a vague mandate to document well. Up to each developer to decide what code to document (possibly none) and how to document. At best, inline comments are scattered through code. User manuals, if they exist, are hand-created.| +| 1 | Team chooses a modern structured-documentation tool, e.g., Doxygen. Developers are required to use Doxygen comments for every major component in their code, e.g., functions, subroutines, structs, classes. Team uses the full-featured structuring features of the tool. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become available. 1,2| +| 2 | Team uses MeerCat to incrementally fill in field content during the Pull Request process, taking some of the burden off of PR reviewers. MeerCat can check for placeholders indicating missing documentation content, and help the developer (PR author) fill them in.| +Eventually, fully-realized structured-documentation is produced and a rich user manual is generated.| ## Comments -1. Using tool support to start the transition to structured-documentation is often feasible. For instance, formatted documentation templates can be inserted at appropriate locations with placeholders for actual content for a developer to fill in. -2. Again, tool support to generate the required fields is often possible, leaving the actual content of the field for the developer to fill in. +1. Aligning what the tool supports in terms of documentation structuring with the Team's documentation goals is a worthwhile but time-intensive effort. Using Doxygen as an example, it has over 100 different fields that can be used. Asking developers to fill in 100 different fields for every component of the system is not reasonable. But choosing which subset to use takes thought on the overall documentation goals of the Team. +2. Using tool support to start the transition to structured-documentation is often feasible. For instance, formatted documentation templates can be inserted at appropriate locations with placeholders for actual content for a developer to fill in. + ### Acknowledgement From 2397145c3eb0f392a2f581512b834e07869dbfa7 Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Thu, 23 Feb 2023 16:06:17 -0800 Subject: [PATCH 4/6] Update project_documentation.md --- ptc_cards/project_documentation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md index 52f5b13d..1f04aa20 100644 --- a/ptc_cards/project_documentation.md +++ b/ptc_cards/project_documentation.md @@ -9,7 +9,7 @@ Improve our team’s project documentation. This includes code documentation and ## Approach -Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. Use MeerCat to find missing documentation and to create it. +Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. Use MeerCat to find missing documentation, giving the developer the chance to create it. ## User Story @@ -25,7 +25,8 @@ Use documentation structuring tools (e.g., Doxygen) that take structured code do | :-------------: | :------------- | | 0 | Team does ad-hoc code documentation, possibly with a vague mandate to document well. Up to each developer to decide what code to document (possibly none) and how to document. At best, inline comments are scattered through code. User manuals, if they exist, are hand-created.| | 1 | Team chooses a modern structured-documentation tool, e.g., Doxygen. Developers are required to use Doxygen comments for every major component in their code, e.g., functions, subroutines, structs, classes. Team uses the full-featured structuring features of the tool. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become available. 1,2| -| 2 | Team uses MeerCat to incrementally fill in field content during the Pull Request process, taking some of the burden off of PR reviewers. MeerCat can check for placeholders indicating missing documentation content, and help the developer (PR author) fill them in.| +| 2 | Team uses MeerCat to incrementally fill in field content during the Pull Request process, taking some of the burden off of PR reviewers. MeerCat can check for placeholders (see comment 2) indicating missing documentation content, and help the developer (PR author) fill them in.| + Eventually, fully-realized structured-documentation is produced and a rich user manual is generated.| From 3335a9c4947876f6142a9d18728790abee4fd85d Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Fri, 24 Feb 2023 09:32:49 -0800 Subject: [PATCH 5/6] Update project_documentation.md --- ptc_cards/project_documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md index 1f04aa20..3cfb6031 100644 --- a/ptc_cards/project_documentation.md +++ b/ptc_cards/project_documentation.md @@ -16,7 +16,7 @@ Use documentation structuring tools (e.g., Doxygen) that take structured code do * **As a** developer, **I want** to document my code, **so that** it is easy understand and potentially change. * **As a** user of the software, **I want** to know what functionality is available to me and how to use it. -* **As a** code reviewer (a Pull-Request reviewer), **I want** to avoid the tedium of searching through files looking for missing documentation. +* **As a** code reviewer (a Pull-Request reviewer), **I want** to avoid the tedium of searching through files looking for missing or erroneous documentation. ## Card(s) @@ -25,7 +25,7 @@ Use documentation structuring tools (e.g., Doxygen) that take structured code do | :-------------: | :------------- | | 0 | Team does ad-hoc code documentation, possibly with a vague mandate to document well. Up to each developer to decide what code to document (possibly none) and how to document. At best, inline comments are scattered through code. User manuals, if they exist, are hand-created.| | 1 | Team chooses a modern structured-documentation tool, e.g., Doxygen. Developers are required to use Doxygen comments for every major component in their code, e.g., functions, subroutines, structs, classes. Team uses the full-featured structuring features of the tool. A good example are the notion of predefined tags/fields like @param for describing each parameter of a function or @brief for a brief description of a component. Auto-generated user manuals now become available. 1,2| -| 2 | Team uses MeerCat to incrementally fill in field content during the Pull Request process, taking some of the burden off of PR reviewers. MeerCat can check for placeholders (see comment 2) indicating missing documentation content, and help the developer (PR author) fill them in.| +| 2 | Team uses MeerCat to incrementally fill in field content during the Pull Request process, taking some of the burden off of PR reviewers. MeerCat can check for placeholders 2 indicating missing documentation content, and help the developer (PR author) fill them in.| Eventually, fully-realized structured-documentation is produced and a rich user manual is generated.| From 2f23a7651d24416a19490a1f1d859458aa5ee8bf Mon Sep 17 00:00:00 2001 From: Stephen Fickas Date: Fri, 24 Feb 2023 09:34:06 -0800 Subject: [PATCH 6/6] Update project_documentation.md --- ptc_cards/project_documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ptc_cards/project_documentation.md b/ptc_cards/project_documentation.md index 3cfb6031..c48ea4fb 100644 --- a/ptc_cards/project_documentation.md +++ b/ptc_cards/project_documentation.md @@ -9,7 +9,7 @@ Improve our team’s project documentation. This includes code documentation and ## Approach -Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. Use MeerCat to find missing documentation, giving the developer the chance to create it. +Use documentation structuring tools (e.g., Doxygen) that take structured code documentation and produce user-level project documentation, e.g., user manuals in html. Use MeerCat to find missing or erroneous documentation, giving the developer the chance to create it or correct it. ## User Story