Going ahead with my drive for professional development, I am taking a deeper dive into Documentation Engineering and learning more about documenta...
For further actions, you may consider blocking this person and/or reporting abuse
Thank you for writing this article. I was unfamiliar with DocOps before, but it has piqued my interest. It seems like a promising approach, though Iād like to see it in action. You mentioned several tools like Jekyll, Hugo, Git, Jenkins, and Travis CI. It would be helpful to see a sample repository that implements DocOps as it still seems somewhat theoretical to me without more tooling.
How do you handle keeping documentation updated with code changes? Tracking updates to documentation in sync with programming changes can be challenging, especially if tools like Swagger aren't used. One approach could be to require documentation updates with each pull request, but I can see this leading to superficial changes, such as unnecessary whitespace edits, just to meet the requirement. How do you address this issue effectively?
Documentation in most companies definitely needs to improve, and this could be a path forward for this improvement
Agree. The article is full of theoretical statements. The author should have added a minimum working example, otherwise what they have presented here is close to nothing.
Hi, thank you for your observation.
Like I said at the start of the article, this was a research-based article. I heard about DocOps and did my research on it. You can think of this article as my notes or findings.
However, I came across this article during my research. Here is a company that has tried DocOps and has more practical than theory.
I hope this helps. Thank you.
Wow, back in 2014 even. The article you referenced also didn't have any working examples, although there was a link to another LinkedIn Article "for more information", but this article was no longer available.
Oh Hmmm š¤
The "more information" Article was available when I was doing my research. I wonder. I'd check.
@whimsicalbison , check it on this link.
DocOps is about treating documentation as an artefact that can be subjected to technology automation as opposed to 'something different' that escapes information technology and can only be dealt with by 'typing documents from scratch one letter at a time' (which is what most industries do). The OP provides an introduction to the topic and some examples of a DocOps platform based on SSGs such as Hugo and Jeykyll. This is ONE possible documentation platform setup, but there are many others.
There are tons of DocOps use cases but the staples of DocOps are document conversion, composition, and embedding and blending. You can find worked out examples using shell scripts (invokable from any CI/CD engine) by following the last two links.
@whimsicalbison , to answer your question, and this is my personal opinion:
Documentation should be done after each milestone is reached.
For example, where I work, each week, the devs are given a milestone or a specific aspect of the project to get to or knock-off. After each milestone is reached, tested, and approved, the docs guy goes in to document that change.
This process also applies to bug fixes and reviews. Such that the documentation only happens have "success" has been achieved.
Wonder what that is like to have a dedicated "docs guy", LOL. Feel like it would be easier to ensure that documentation gets written if there was someone dedicated to that rather than it being everyone's responsibility, and of course everyone has too much going on already
Orgs actually do. That's why they hire technical writers or documentation engineers or DevRel. It's become an increasingly common trend now.
The likes of Jekyll and Hugo fall under the category of SSGs, within general-purpose documentation platforms, but give that you've mention Swagger, it's worth looking at documentation platforms holistically, including not only SSGs but specialist documentation platforms such as Swagger.
The choice of a CI/CD engine such as Jenkins or Travis CI is a tactical one. Many DocOps automation workflows may be implemented as plugins for established platforms such as Atlassian Confluence. Last but not least, what is it that such CI/CD pipelines do anyway? In most cases, is firing document conversion utilities such as Pandoc for the purpose of composing content.
I'm curious how anyone can retain their memory on milestones of development within devops without documentation of exact steps. Given the huge potential for human error when connecting services, applying specific syntax with formulas, from docker to bash, ssl, node, api development, cors, passing secrets, authentication and security, bundle sizing for cost etc. We are all experts in specific areas of development but lack all knowledge off the top of our head for such a vast detail of administrating and configuration.
Well.. I would try out DocOps
Thanks, my leader
What are your opinions on DocOps? š¤
Are you willing to implement it in your organization?
Let me know!
Nice read
Thank you!