What follows is the text of a post I made to the #community-help-wanted channel in the awesome Write the Docs Slack community. The offer is extended to anyone earnest who comes across this post.
Up till now, the biggest single challenge of my time as a DocOps specialist and contractor has been getting non-programmers (tech writers, project managers, even legal workers) up and running in a proper docs-as-code environment. By definition, docs-as-code relies on "coders' tools", and getting comfortable with a "development environment" has always been a challenge, even for committed engineers. For the past decade, I have worked to bridge the gap for less-technical individuals and teams who nevertheless need to use these tools day to day.
Today I am launching without fanfare my attempt to finally open source the solution I've been developing for over 5 years, as I have finally settled on what I think is the optimal approach. It is Docker based but aimed at people with no prior knowledge of Docker or any of the environments or docs tools the solution makes available. This project provides everything my clients have needed to carry out a wide range of authoring and processing tasks: Git, Ruby, Node.js, Python, Pandoc, Vale, OpenAPI tools, LibreOffice CLI tools, and more.
It's called DocOps Box (as in, document operations in a box), and I have both a request and an offer -- my reason for posting here instead of in #community-showcase, which will hopefully come soon.
I need individual volunteers who either ARE NOW or ONCE WERE a "non-developer newcomer" to the docs-as-code world, especially Mac or Windows users, to try this out and give me feedback. I have tested it thoroughly, but there are sure to be bugs and hidden sticking points.
If you're truly new to DocOps/docs-as-code, my offer is that if you'll try DocOps Box as a potential bridge to competence with these tools and workflows, I will personally and directly support you getting up and running with docs-as-code, even if that means some alternative to this project. In other words, if you'll take this plunge, I'll hold your hand through any sticking point or give you initial guidance on what might be a more appropriate system or approach for your situation. I'll either make DocOps Box work for you, or I'll help you get unstuck on an alternate path. Your feedback will be that valuable to me, even if you decide this solution isn't for you.
If you are an intermediate or expert docs-as-coder, you can help by playing the beginner role. If you are adept with virtual machines, maybe you can run a fresh Windows or MacOS VM and come at this problem as a novice, starting just with the DocOps Box README. One thing I would like to know from you is whether you would use or recommend this for coworkers/colleagues who need to work with your content, or why not -- what does it lack or get wrong?
In either case, I think there will be no harm done for anyone spending time with the README for this project, which I have put truly countless hours of work into and intend to upkeep indefinitely, or the tools I introduce: the prerequisites for all OSes are solid choices (or I wouldn't be requiring them), and the Docker image I'm shipping is hopefully at least worth playing with.
If you want to set a goal like "Get a Jekyll/Antora/Docusaurus/Sphinx site building/serving locally", all the better. If you wish, we can discuss it in the comments here or start a thread in the GitHub Issues for DocOps Box.
If you've ever wanted to try Asciidoctor, Vale, Pandoc, Docker, VS Code, or other docs-as-code tools but were waiting for more help, now is your chance! (To be fair, my offer to personally support WTDers on this journey will probably extend past this immediate experiment, so only the most interested need jump in now.)
Without further ado, for the adventurous and soon-to-be-appreciated: https://github.com/DocOps/box
This seems like as good a place as any to start/continue conversations around this offer/request. Comment below or create your own issue if you want to participate.
What follows is the text of a post I made to the
#community-help-wantedchannel in the awesome Write the Docs Slack community. The offer is extended to anyone earnest who comes across this post.Up till now, the biggest single challenge of my time as a DocOps specialist and contractor has been getting non-programmers (tech writers, project managers, even legal workers) up and running in a proper docs-as-code environment. By definition, docs-as-code relies on "coders' tools", and getting comfortable with a "development environment" has always been a challenge, even for committed engineers. For the past decade, I have worked to bridge the gap for less-technical individuals and teams who nevertheless need to use these tools day to day.
Today I am launching without fanfare my attempt to finally open source the solution I've been developing for over 5 years, as I have finally settled on what I think is the optimal approach. It is Docker based but aimed at people with no prior knowledge of Docker or any of the environments or docs tools the solution makes available. This project provides everything my clients have needed to carry out a wide range of authoring and processing tasks: Git, Ruby, Node.js, Python, Pandoc, Vale, OpenAPI tools, LibreOffice CLI tools, and more.
It's called DocOps Box (as in, document operations in a box), and I have both a request and an offer -- my reason for posting here instead of in #community-showcase, which will hopefully come soon.
I need individual volunteers who either ARE NOW or ONCE WERE a "non-developer newcomer" to the docs-as-code world, especially Mac or Windows users, to try this out and give me feedback. I have tested it thoroughly, but there are sure to be bugs and hidden sticking points.
If you're truly new to DocOps/docs-as-code, my offer is that if you'll try DocOps Box as a potential bridge to competence with these tools and workflows, I will personally and directly support you getting up and running with docs-as-code, even if that means some alternative to this project. In other words, if you'll take this plunge, I'll hold your hand through any sticking point or give you initial guidance on what might be a more appropriate system or approach for your situation. I'll either make DocOps Box work for you, or I'll help you get unstuck on an alternate path. Your feedback will be that valuable to me, even if you decide this solution isn't for you.
If you are an intermediate or expert docs-as-coder, you can help by playing the beginner role. If you are adept with virtual machines, maybe you can run a fresh Windows or MacOS VM and come at this problem as a novice, starting just with the DocOps Box README. One thing I would like to know from you is whether you would use or recommend this for coworkers/colleagues who need to work with your content, or why not -- what does it lack or get wrong?
In either case, I think there will be no harm done for anyone spending time with the README for this project, which I have put truly countless hours of work into and intend to upkeep indefinitely, or the tools I introduce: the prerequisites for all OSes are solid choices (or I wouldn't be requiring them), and the Docker image I'm shipping is hopefully at least worth playing with.
If you want to set a goal like "Get a Jekyll/Antora/Docusaurus/Sphinx site building/serving locally", all the better. If you wish, we can discuss it in the comments here or start a thread in the GitHub Issues for DocOps Box.
If you've ever wanted to try Asciidoctor, Vale, Pandoc, Docker, VS Code, or other docs-as-code tools but were waiting for more help, now is your chance! (To be fair, my offer to personally support WTDers on this journey will probably extend past this immediate experiment, so only the most interested need jump in now.)
Without further ado, for the adventurous and soon-to-be-appreciated: https://github.com/DocOps/box
This seems like as good a place as any to start/continue conversations around this offer/request. Comment below or create your own issue if you want to participate.