HPCC-32345 How to contribute to platform documentation

Signed-off-by: Jim DeFabia <[email protected]>

devdoc/docs/ContributeDocs.md

@@ -18,7 +18,8 @@ When you create a new feature or function, clear documentation is
 crucial for both internal teams and external users. You worked hard on
 the feature, so it deserves proper notice and usage.
 
-Contributions to the platform are always welcome, and we strongly encourage developers and users to contribute documenation
+Contributions to the platform are always welcome, and we strongly encourage 
+developers and users to contribute documentation.
 
 You can contribute on many levels:
 
@@ -88,13 +89,14 @@ required and optional components to include in a document.
     -   **Detailed configuration options:** If the feature offers
         advanced settings or customizations, provide in-depth
         instructions for experienced users.
-        This is similar to the way some options command line program's usage are only displayed using the verbose option. 
+        This is similar to the way some options command line program's usage 
+        are only displayed using the verbose option. 
 
 2.  **API Reference (for technical audiences)**
 
-    -   **Technical specifications:** For features with an API
-        component, include detailed API reference documentation for
-        developers integrating it into their applications.
+    -   **Technical specifications:** For features with an API component, 
+        include detailed API reference documentation for developers integrating 
+        it into their applications.
 
 3.  **FAQs**
 
@@ -122,8 +124,8 @@ required and optional components to include in a document.
 
 -   **Clarity and Conciseness:** Use clear, concise language and
     maintain a consistent structure for easy navigation. Always use
-    present tense, active voice. Remember, you’re writing for users and programmers, not academics, so keep it simple and
-    straightforward. 
+    present tense, active voice. Remember, you’re writing for users and 
+    programmers, not academics, so keep it simple and straightforward. 
     See the [HPCC Style Guide](HPCCStyleGuide) for additional guidance.
 
 -   **Visual Aids:** Screenshots, diagrams, and flowcharts can
@@ -136,24 +138,55 @@ required and optional components to include in a document.
 By following these guidelines and including the required and optional
 components, you can create comprehensive documentation that empowers
 users and streamlines the adoption of your new software feature.
+
 ### Who should write it?
-The boundary between a developer's responsibilities and the documentation team’s responsibility is not cast in stone. However, there are some guidelines that can help you decide what your responsibility is. Here are some examples:
+
+The boundary between a developer's responsibilities and the documentation 
+team’s responsibility is not cast in stone. However, there are some guidelines 
+that can help you decide what your responsibility is. Here are some examples:
+
 #### Changing the default value of a configuration setting
-This typically needs a simple one or two word change in the area of the documentation where that setting is documented. However, the change could impact existing deployments or existing code and therefore it might also require a short write-up for the Red Book and/or Release Announcement.
-If the setting is used by both bare-metal and containerized, you should provide information about how the new setting is used in each of those deployments.
+
+This typically needs a simple one or two word change in the area of the 
+documentation where that setting is documented. However, the change could impact 
+existing deployments or existing code and therefore it might also require a short 
+write-up for the Red Book 
+and/or Release Announcement.
+If the setting is used by both bare-metal and containerized, you should provide 
+information about how the new setting is used in each of those deployments.
+
 #### Adding or modifying a Language keyword, Standard Library function, or command line tool action
-This needs some changes to existing documentation so the best way to provide the information is in a documentation Jira issue.
+
+This needs some changes to existing documentation so the best way to provide the 
+information is in a documentation Jira issue.
 If it s a new keyword, function, or action, a brief overview should be included.
-For a Standard Library function, the developer should update the Javadoc comment in the appropriate ECL file. For a command line tool change, the developer should update the Usage section of the code.
+For a Standard Library function, the developer should update the Javadoc comment 
+in the appropriate ECL file. For a command line tool change, the developer should 
+update the Usage section of the code.
+
 #### Adding a new feature that requires an overview.
-This is a candidate for either an MD file, a blog, or both. Since there should have been some sort of design specification document, that could easily be repurposed as a good start for this.  
+
+This is a candidate for either an MD file, a blog, or both. Since there should have 
+been some sort of design specification document, that could easily be repurposed as 
+a good start for this. 
+
 #### A feature/function that is only used internally to the system
-Since this is information that is probably only of interest to other developers, a write-up in the form of an MD file in the repo is the best approach. If it affects end-users or operations, then a more formal document or a blog might be a good idea. 
-If it affects existing deployments or existing code, then a Red Book notice might also be needed.
+
+Since this is information that is probably only of interest to other developers, 
+a write-up in the form of an MD file in the repo is the best approach. If it 
+affects end-users or operations, then a more formal document or a blog might be 
+a good idea. 
+If it affects existing deployments or existing code, then a Red Book notice might 
+also be needed.
+
 #### Extending the tests in the regression suite
-New tests are frequently added and the regression suite readme files should be updated at the same time. 
-If the tests are noteworthy, we could add a mention in the Platform Release Notes.  
+
+New tests are frequently added and the regression suite readme files should be 
+updated at the same time. If the tests are noteworthy, we could add a mention in 
+the Platform Release Notes.  
+
 ### Placement
+
 In general, it makes sense to keep simple documentation near the code. For
 example, a document about ECL Agent should go in the ECLAgent folder.
 However, there are times where that is either not possible or a document
@@ -166,32 +199,40 @@ options as shown below.
 
 **devdoc**/**docs**: This is a folder for documents about documentation.
 
-**userdoc**: This is a collection of docs targeted toward the end-user
+**devdoc**/**userdoc**: This is a collection of docs targeted toward the end-user
 rather than developers.
 
-This is primarily for informal documents aimed at end-users. This info can and should be incorporated into the formal docs. 
-**userdoc**/**troubleshoot**: Information related to troubleshooting
+This is primarily for informal documents aimed at end-users. This info can and should 
+be incorporated into the formal docs. 
+**devdoc**/**userdoc**/**troubleshoot**: Information related to troubleshooting
 particular components
 
-**userdoc**/**azure**: Useful information about Azure Cloud portal and
+**devdoc**/**userdoc**/**azure**: Useful information about Azure Cloud portal and
 cli
 
-**userdoc**/**roxie**: Useful information for running roxie
+**devdoc**/**userdoc**/**roxie**: Useful information for running roxie
 
-**userdoc**/**thor**: Useful information for running thor
+**devdoc**/**userdoc**/**thor**: Useful information for running thor
 
-**userdoc**/**blogs**: COMING SOON: Location and storage of original
+**devdoc**/**userdoc**/**blogs**: COMING SOON: Location and storage of original
 text for blogs. It also has docs with guidelines and instructions on
 writing Blogs
 
 #### Pull Requests
 
 You can include your documentation with your code in a Pull Request or
 create a separate Jira and Pull Request for the documentation. This
-depends on the size of the code and doc. For a large project or change, a separate Pull request for the documentation is better. 
+depends on the size of the code and doc. For a large project or change, a separate 
+Pull request for the documentation is better. This might allow the code change to be 
+merged faster. 
 
 #### Documentation Jira Issues
-For minor code changes, for example the addition of a parameter to an existing ECL keyword, you can request a documentation change in a Jira issue. 
+
+For minor code changes, for example the addition of a parameter to an existing ECL 
+keyword, you can request a documentation change in a Jira issue. 
 You should provide sufficient details in the Jira. 
 
-For example, If you add an optional parameter named Foo, you should provide details about what values can be passed in through the Foo paramater and what those values mean. You should also provide the default value used if the parameter is omitted.
+For example, If you add an optional parameter named Foo, you should provide 
+details about what values can be passed in through the Foo parameter and what 
+those values mean. You should also provide the default value used if the 
+parameter is omitted.