3:31 p.m.
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?
9:20 p.m.
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!
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
6:13 a.m.
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/
--
Lukáš Růžička
FEDORA QE, RHCE
Red Hat
<https://www.redhat.com>
Purkyňova 115
612 45 Brno - Královo Pole
lruzicka(a)redhat.com
TRIED AND PERSONALLY TESTED, ERGO TRUSTED. <https://redhat.com/trusted>
10:31 a.m.
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.
12:10 p.m.
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.
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
4:20 p.m.
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(a)lists.fedoraproject.org
To unsubscribe send an email to server-leave(a)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
--
Lukáš Růžička
FEDORA QE, RHCE
Red Hat
<https://www.redhat.com>
Purkyňova 115
612 45 Brno - Královo Pole
lruzicka(a)redhat.com
TRIED AND PERSONALLY TESTED, ERGO TRUSTED. <https://redhat.com/trusted>
10:15 a.m.
Am 20.12.2020 um 23:20 schrieb Lukas Ruzicka
<lruzicka(a)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}(a)fedoraproject.org or use the mailing list so we can
work out a solution.“ ?
Best
Peter
12:09 p.m.
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.
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
4:34 p.m.
Am 19.12.2020 um 19:09 schrieb Matthew Miller
<mattdm(a)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.
4:37 p.m.
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).
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
5:25 p.m.
Am 19.12.2020 um 23:37 schrieb Matthew Miller
<mattdm(a)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.
4:25 p.m.
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(a)lists.fedoraproject.org
To unsubscribe send an email to server-leave(a)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
--
Lukáš Růžička
FEDORA QE, RHCE
Red Hat
<https://www.redhat.com>
Purkyňova 115
612 45 Brno - Královo Pole
lruzicka(a)redhat.com
TRIED AND PERSONALLY TESTED, ERGO TRUSTED. <https://redhat.com/trusted>
6:52 p.m.
Am 20.12.2020 um 23:25 schrieb Lukas Ruzicka
<lruzicka(a)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
4:51 a.m.
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
1207
days inactive
1222
days old
server@lists.fedoraproject.org
13 comments
3 participants
participants (3)
-
Lukas Ruzicka -
Matthew Miller -
Peter Boy