Adding Doc-as-code article #269
Conversation
There was a problem hiding this comment.
Hi @st13g,
Thank you for your work on this! You have a good base, it is well structured and summarized!
I have left quite a lot of comments, and I want to clarify that what I did (the editing/reviewing process) is the easy part of technical writing. What you did (knowing what to write, structuring, and writing) is the hard part. My suggestions don't change anything regarding the efforts you have made, so thank you for that!
Improvements and suggestions:
- Before submitting a pull request, it is a good practice to check for grammar errors. In our project, you can use the "make spellchecks" command. You can follow the how-to guide and try the command "make spellchecks" at the end. I have put some examples in the my review comments, but I'll let you correct the rest of the errors.
- I have found some sentences that could be more concise. I have highlighted a few of them in my review comments, but once again I'll let you review the rest of the document. A good tip is to read sentences out loud to find when you take a pause for breath. Those pauses are usually where you would find the end of a sentence or a comma.
- Thanks to your document, I have realized that I don't want the article to be a copy paste of what was said in the video. It can extend a bit the ideas that where shared in the video. You have already started the work on this, and I have highlighted a few ideas that could be improved upon.
- Lastly, I forgot to link to the style guide in the initial issue (sorry about that!). You can review the style guide and see if your document could be improved with those new insights!
If you have any question regarding my comments, please don't hesitate to ask.
| | **Goals** | **Tools** | **Reason** | | ||
| |----------|----------|----------| | ||
| | Content authoring | Text editors | Not binary format, quite easy to start | | ||
| | Formatting, styling | Markup languages | The formatting and styling is based in semanticity as oppossed to the formatting being applied directly to the content enabling multiple output formats | |
There was a problem hiding this comment.
typos and suggestion:
I would make it coherent by starting with a verb like with the other rows.
| | Formatting, styling | Markup languages | The formatting and styling is based in semanticity as oppossed to the formatting being applied directly to the content enabling multiple output formats | | |
| | Formatting and styling | Markup languages | Based on semanticity as opposed to being applied directly to the content. Enables multiple output formats | |
| @@ -0,0 +1,70 @@ | |||
| # Documentation as Code: A Comprehensive Study Guide | |||
There was a problem hiding this comment.
suggestion:
To follow our style guide, all headings and headlines should be sentence case. Only the first letter of the first word should be capitalised, unless it is a product name like Ubuntu for example.
| # Documentation as Code: A Comprehensive Study Guide | |
| # Documentation as Code: A comprehensive study guide |
| @@ -0,0 +1,70 @@ | |||
| # Documentation as Code: A Comprehensive Study Guide | |||
| **Presented by:** [Robert Krátký](https://github.com/rkratky) at Documentation Office Hours - ODH-015 | |||
There was a problem hiding this comment.
suggestion:
I would use the name "Documentation Community Hours" which is the new name of the "Documentation Office Hours".
| **Presented by:** [Robert Krátký](https://github.com/rkratky) at Documentation Office Hours - ODH-015 | |
| **Presented by:** [Robert Krátký](https://github.com/rkratky) during the Documentation Community Hours. |
| 3. **Better Integration:** Documentation can be included in the "definition of done" ensuring it's part of product planning and validation, just like code. | ||
| 4. **Shared Responsability:** QA teams and developers can validate documentation, fostering alignment and reducing the perception of docs as an afterthought. | ||
| 5. **Open Tooling Capabilities:** Using open source tooling for documentation promotes collaboration and consistency with the software development process. | ||
| Documentation integrated into development workflow |
There was a problem hiding this comment.
suggestion:
I would add this sentence in the third section.
| Documentation integrated into development workflow | |
| 3. **Better Integration:** Documentation is integrated into the development workflow. For example, documentation tasks can be included in the "definition of done" ensuring they are part of product planning and validation, just like code. | |
| 4. **Shared Responsability:** QA teams and developers can validate documentation, fostering alignment and reducing the perception of docs as an afterthought. | |
| 5. **Open Tooling Capabilities:** Using open source tooling for documentation promotes collaboration and consistency with the software development process. |
|
|
||
| **Link to the video:** [Documentation as Code](https://www.youtube.com/watch?v=AVNfH99KiME) | ||
|
|
||
| ## What does "Docs as Code" mean? |
There was a problem hiding this comment.
suggestion:
I would explain that "Documentation as Code" is abbreviated with "Docs as Code" and use "Docs as Code" in the rest of the document with this specific case. Both "The docs as code approach" and "Also documentation as code enables valuable automation" were used in the document, and they aren't capitalized. Can you please review the rest of the document to make it more consistent?
| This approach also offers flexibility in migrating formats, reduces organizational overhead, and aligns processes across teams, | ||
| enabling consistent automation and smoother coordination with software releases. | ||
|
|
||
| ## Challenges and Considerations |
There was a problem hiding this comment.
This section is also very well done, with clear ideas and short explanations. What I really like about this section is that you make it easy for skimming (easy for the users to find information in the page).
| ### Automation Opportunities | ||
| Also documentation as code enables valuable automation, particularly for autogenerated documentation that lives alongside the code. (e.g.incorrect autogenerated documentation actually | ||
| can catch software errors before release). Also keeping documentation in the same repository as code significantly simplifies testing purposes and automation. |
There was a problem hiding this comment.
suggestion:
I feel like this part would be a great fit for the section "Benefits of Documentation as Code" and subsection "Organizational Benefits". What do you think?
| ## Additional Commentaries | ||
|
|
||
| The docs as code approach offers key benefits like enabling documentation review in developers familiar environments (Github/Gitlab) and simpliying change tracking by keeping docs with code, | ||
| but also presents challenges such as tying documentation to development cycles and release freezes, difficulty switching between markup languages, significant time spent on formatting issues, | ||
| and the need for specialized tools that handle both writing and technical aspects effectively, potentially requiring dedicated staff for markup-related tasks despite its growing popularity. |
There was a problem hiding this comment.
typo and suggestion:
I think this section could be a great summary. What do you think?
I would improve it's clarity by making the sentences shorter. If you agree, I'll let you modify it!
| ## Additional Commentaries | |
| The docs as code approach offers key benefits like enabling documentation review in developers familiar environments (Github/Gitlab) and simpliying change tracking by keeping docs with code, | |
| but also presents challenges such as tying documentation to development cycles and release freezes, difficulty switching between markup languages, significant time spent on formatting issues, | |
| and the need for specialized tools that handle both writing and technical aspects effectively, potentially requiring dedicated staff for markup-related tasks despite its growing popularity. | |
| ## Summary | |
| The docs as code approach offers key benefits like enabling documentation review in developers familiar environments (Github/Gitlab) and simplifying change tracking by keeping docs with code, | |
| but also presents challenges such as tying documentation to development cycles and release freezes, difficulty switching between markup languages, significant time spent on formatting issues, | |
| and the need for specialized tools that handle both writing and technical aspects effectively, potentially requiring dedicated staff for markup-related tasks despite its growing popularity. |
| but also presents challenges such as tying documentation to development cycles and release freezes, difficulty switching between markup languages, significant time spent on formatting issues, | ||
| and the need for specialized tools that handle both writing and technical aspects effectively, potentially requiring dedicated staff for markup-related tasks despite its growing popularity. | ||
|
|
||
| ### Branching and Versioning |
There was a problem hiding this comment.
suggestion:
This section could be a great fit for the "Challenge and considerations" section. What do you think?
|
|
||
| ### Developer Perspective | ||
| 1. **Developer Familiarity & Confort:** Developers already know the tools (Git, scripting,etc) making it easier for them to contribute to documentation. | ||
| 2. **Higher Engament:** Documentation becomes a natural part of the project, encouraging developers to treat it seriously and make quick, one-off fixes. | ||
| 3. **Better Integration:** Documentation can be included in the "definition of done" ensuring it's part of product planning and validation, just like code. | ||
| 4. **Shared Responsability:** QA teams and developers can validate documentation, fostering alignment and reducing the perception of docs as an afterthought. | ||
| 5. **Open Tooling Capabilities:** Using open source tooling for documentation promotes collaboration and consistency with the software development process. | ||
| Documentation integrated into development workflow | ||
|
|
There was a problem hiding this comment.
Very great section: well summarized and clear. Great work!
|
Hi @st13g, how are you doing? If you need help or a working session with me, so we can go through my comments together, please don't hesitate! |
Fixes #229
Please let me know if something needs to be changed or improved, thanks!! :D