At the recent Fedora Server Reboot meeting, an editorial group was set up to update our PRD: m3xboy (Eduard Lucena), langdon (Langdon White), and pboy (Peter Boy, it's me). We should start to put the work in motion. The next IRC meeting is planned for January. We should then have a first proposal.
Looking back on the discussion, the first thing we have to decide upon is the tool to use. One idea was hackMD (https://hackmd.io/pricing#), a commercial online platform and markdown editor, free for individuals and public groups.
Maybe I'm a bit old fashioned but I'd rather prefer a Fedora project resource if it exists and is available, maybe something like laverna (https://laverna.cc/)? A real OSS markdown editor available as on premise installable online tool as well as local installable (Linux, Max, Win) with online synchronization.
However, I would much rather use a tool with some professional writing functionality. For our purpose, even LibreOffice would suffice. It provides a tracking of changes within text lines, a comment and discussion function on selectable text passages directly in the margin of the page, a merging of different editing statuses, and some more. Although the final version would have to be downgraded to Markdown, thanks to pandoc it is quite feasible. We would then have to upload and download the file. Would we have a place in the Fedora infrastructure to do this?
In the next step, we should decide on a targeted table of contents, a heading and a very short abstract of the intended "message" and its content, so that we have a focus for the text.
In the discussion, the prevailing opinion was to essentially keep the structure.
The sections "Vision" and "Mission" have so far been mentioned as needing discussion (I would argue for keeping them).
The section "Featured Server Roles" was described by Stephen Gallagher as completely outdated. Who can contribute detailed information on this?
That's my ideas so far. @m3xboy and @langdon should we arrange an IRC meeting at short notice? Or do we want to continue discussing here?
On Fri, Dec 18, 2020 at 10:31:56PM +0100, Peter Boy wrote:
merging of different editing statuses, and some more. Although the final version would have to be downgraded to Markdown, thanks to pandoc it is quite feasible. We would then have to upload and download the file. Would we have a place in the Fedora infrastructure to do this?
You can use the Fedora People space: https://fedoraproject.org/wiki/Infrastructure/fedorapeople.org
Personally, I find keeping shared versions of files in sync to be very hard, which is why I prefer the online collaborative tools. But whoever is doing the work should decide!
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.
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:
* AsciiDoc is similar to Markdown, so the basics can be learnt in a twist of time. * AsciiDoc is also used at Red Hat, so we could probably cooperate with Red Hat documentation teams - after all, they will need such documentation after some time. * Anybody can use whatever editor they like, some editors (Atom for example) have a live AsciiDoc preview, some do not, but it can be built anytime manually on your CLI. * We do not need to look after anything, because the infrastructure is already set up and working. * Fedora even has a dedicated documentation guy, Petr Bokoč, who is really knowledgeable and helpful, so I think he should be the one to speak about this, too. I am adding him to this thread.
Please, let's not waste time and resources on reinventing the wheel.
[1]: https://docs.fedoraproject.org/en-US/fedora-docs/contributing/ [2]: https://docs.fedoraproject.org/en-US/docs/
Am 19.12.2020 um 13:13 schrieb Lukas Ruzicka lruzicka@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.
On Sat, Dec 19, 2020 at 05:31:12PM +0100, Peter Boy wrote:
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.
Yes, that's true.
Although Fedora doesn't have "products" per se (we don't sell anything!), we want the editions to follow a product mindset in addressing user problems.
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 ...".
Although I really use vim with syntax highlighting, I did not recommend it anywhere in my previous text - I only mentioned Atom and Live Previews. :D
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.
Well, I believe that "professional writers" who want to write about Linux servers are fully aware of various tools to write texts and they probably know something about text format conversion, unless by "professional" you mean people who, for instance, just hand-in typewritten novels in Word or a similar application. But even the Word users can still use it to write the text and have it converted by pandoc, which seems to be able to convert from DOCX to ADOC. There is no need to think they will not be able to learn a few simple steps.
And if there still is somebody who wants to write something about Fedora and they only want to do it in a certain format, I am willing to help them to convert their text to AsciiDoc providing that I can open the format on my Fedora machine.
Regards, Lukas
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. _______________________________________________ server mailing list -- server@lists.fedoraproject.org To unsubscribe send an email to server-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/server@lists.fedoraproject.org
Am 20.12.2020 um 23:20 schrieb Lukas Ruzicka lruzicka@redhat.com:
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 ...".
Although I really use vim with syntax highlighting, I did not recommend it anywhere in my previous text - I only mentioned Atom and Live Previews. :D
You have not recommended vi, in fact. I was (implicitly) referring to the Fedora contributor invitation page https://docs.fedoraproject.org/en-US/fedora-docs/contributing/prerequisites/
Well, I believe that "professional writers" who want to write about Linux servers are fully aware of various tools to write texts and they probably know something about text format conversion, unless by "professional" you mean people who, for instance, just hand-in typewritten novels in Word or a similar application. But even the Word users can still use it to write the text and have it converted by pandoc, which seems to be able to convert from DOCX to ADOC. There is no need to think they will not be able to learn a few simple steps.
I agree. Unfortunately there is no proven workflow for this. If you use e.g. the (here so maligned) LibreOffice with the default template, an export with Pandoc yields a result that requires a lot of postprocessing. Possibly an adapted template could improve the result.
And if there still is somebody who wants to write something about Fedora and they only want to do it in a certain format, I am willing to help them to convert their text to AsciiDoc providing that I can open the format on my Fedora machine.
Thank you very much. That would be very helpful in such a case. This gives me the idea, wouldn't it be beneficial and more encouraging to add a paragraph on the said contributor page, like: "If you use or need to use any of the other common writing tools, please contact {contactdocs}@fedoraproject.org or use the mailing list so we can work out a solution.“ ?
Best Peter
On Sat, Dec 19, 2020 at 01:13:46PM +0100, Lukas Ruzicka wrote:
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.
Yes, and it would be nice for the result to end up on docs.fedoraproject.org rather than the wiki.
Am 19.12.2020 um 19:09 schrieb Matthew Miller mattdm@fedoraproject.org:
Yes, and it would be nice for the result to end up on docs.fedoraproject.org rather than the wiki.
But where could that be put in place? Quick Docs seems a bit strange for such a document.
On Sat, Dec 19, 2020 at 11:34:22PM +0100, Peter Boy wrote:
Yes, and it would be nice for the result to end up on docs.fedoraproject.org rather than the wiki.
But where could that be put in place? Quick Docs seems a bit strange for such a document.
We'd set up a space specifically for Server. Click on IoT, Silverblue, or CoreOS on the front page https://docs.fedoraproject.org/.
In fact, it might make most sense to have _two_ areas, one for the server _project_ (linked in the bottom half of the front page) and one for user-focused documents (linked in the top half).
Am 19.12.2020 um 23:37 schrieb Matthew Miller mattdm@fedoraproject.org:
On Sat, Dec 19, 2020 at 11:34:22PM +0100, Peter Boy wrote:
Yes, and it would be nice for the result to end up on docs.fedoraproject.org rather than the wiki.
But where could that be put in place? Quick Docs seems a bit strange for such a document.
We'd set up a space specifically for Server. Click on IoT, Silverblue, or CoreOS on the front page https://docs.fedoraproject.org/.
I would very much appreciate such a way. I had raised this as an idea earlier in another thread but was afraid it would be too much of an intrusion.
In fact, it might make most sense to have _two_ areas, one for the server _project_ (linked in the bottom half of the front page) and one for user-focused documents (linked in the top half).
Even better (and it inspires me to polish up my aforementioned typewriter :-) )
But first we should prove that we can successfully implement something as comparatively simple as the PRD update.
Even better (and it inspires me to polish up my aforementioned typewriter :-) )
But first we should prove that we can successfully implement something as comparatively simple as the PRD update.
Once it is agreed, that we want to do it in the Git repository and use Antora build it for docs.fedoraproject.org, I can cooperate with Petr on setting up the repository in the proper space and we can use the usual Git workflow to edit the text.
If you want to do it in some other way, which is more user friendly, let me know how and where and I will join.
Lukas
server mailing list -- server@lists.fedoraproject.org To unsubscribe send an email to server-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/server@lists.fedoraproject.org
Am 20.12.2020 um 23:25 schrieb Lukas Ruzicka lruzicka@redhat.com: ... Once it is agreed, that we want to do it in the Git repository and use Antora build it for docs.fedoraproject.org, I can cooperate with Petr on setting up the repository in the proper space and we can use the usual Git workflow to edit the text.
If we are going to change and add to the existing, extensive text, then the Fedora workflow is the only sensible one. I reckon.
Regarding the aforementioned intention to include the Fedora Server edition in the System Administration Guide (which could be the next project after the PRD update), I would like to ask the existing authors how this could be done. Could you also support this project?
Thanks Peter
So far, a number of suggestions for updating our PRD have been made by several stakeholders.
As a next step, I could offer to compile a concrete text proposal for a new PRD from these around the middle of next week. This could be the basis for further discussion and decision, so that we could have a new version by the end of January.
If anyone is already working on or planning to work on a new concrete text, please let us know briefly to avoid duplication of effort.
A happy new year
Peter
server@lists.fedoraproject.org
-
Lukas Ruzicka -
Matthew Miller -
Peter Boy