Am 19.12.2020 um 13:13 schrieb Lukas Ruzicka
<lruzicka(a)redhat.com>:
I am not very sure about the PRD acronym, but I tend to believe that it stands for
"product documentation". If not, still please read my point.
PRD stands for „Product Requirements Document“ and is currently part of the Fedora
MediaWiki at
https://fedoraproject.org/wiki/Server/Product_Requirements_Document. It is
not part of the product documentation in the strict sense, it is rather an internal
programmatic orientation and planning paper of the Fedora Server working group.
Eventually we'll probably simply have to edit the WIKI page, I reckon. Is that right?
So the source of the text then would not matter.
As a former technical writer, I would suggest we do it "the real
Fedora way", because there is already a workflow [1] as well as a portal where all
Fedora documentation is presented [2] to the end user.
In short, Fedora documentation uses a CI Git workflow, where the source files (written in
AsciiDoc) reside in branches and are built upon a trigger by Antora framework and the
result is immediately published.
The advantages of this approach are:
….
I’m fully aware of "the real Fedora way“ und fully agree with it. And I share the
hope that the plan to lower the entry barriers for developers as well as community
members, and to get more contributions, will work.
As an aside, recommending "vim with syntax highlighting for writing and Docker
container for preview" reads to me something like "retrieve your mechanical
typewriter from the attic ...". As a scientist, I have been involved in writing and
publishing for many years, and I have never had such a request from a publisher, not even
technical publishers like IBM's ITSO or Springer. The „real Fedora way" makes it
easier for developers and community members, but increases the effort for (and possibly
discourages) professional writers who have become accustomed to the extensive
functionality of their writing tools. It would be nice if we would find an easy way for
them too.
But back to business. As you put pbokoc in CC, he and perhaps you have been working on the
"System Administration Guide". We have discussed in the server group that it
would be advantageous to add items regarding the server edition to this guide (in the
Fedora way, of course). I would like to know if (and if so, how) this would fit into the
current concept and ongoing work on the guide, or perhaps someone is already working on
it.
Thanks for your input.