I used to do HTML websites when notepad and FTP were all the rage, and now I am trying to get back into programming.
My original idea was to start with RUBY on RAILS but document everything I need to learn along the way, and to make those documents available somewhere…
I have a setup consisting of an old thinkpad with fedora silverblue as a daily driver, and a imac2011 as a staging with fedora server (and web linux VM something…for production environment), and would love to keep all my findings documented and published… maybe as a Bi weekly or monthly column at Magazine.
I am not saying I am a pro… on the contrary, but celebrating little successes Is the way to go for me, and what I love in Linux.
Please feel free to ping me if you want me as “regular” contributor.
Joao
Hi, we are working on an initiative to improve Fedora Docs and looking for contributors / authors for all sorts of topics. So I’m very interested, what docs you have in mind.
Your docs about your experiences with ROR would perfectly fit into Fedora QuickDocs. Maybe even you could add a description, how Ruby and ROR are organized and structured in Fedora. And your docs would be permanently available, much better than in after some time forgotten older Magazine articles. And you can update it when something new arrives and keep it informative.
And just in case you would like to package some ROR application, I would have some ideas, too (wit my Fedora Server hat on).
I would be delighted if we could come to an arrangement.
My idea was to document everything, but more like a personal journey. Every time I try to do something in Linux, I am offered with a gazillion choices and learning journeys.
Next up would be GIT as a tool in Fedora Silverblue
Use this GIT with my Part II document…
Do some RoR documentation (basic level, MVC, Database scafolding, and looks using a front end framework ) while I develop my idea- Sharing my Github project in the meantime: A household cost sharing app… (Yes, I am an economist, married to another one, and we use excel for this)
Push it to my fedora server using containers (install and configure a server, Cockpit, SELINUX, containers)
Just have in mind that ALLL THIS IS NEW to me. :D:D:D… it might take a little time to do and document… so it is hard to “commit” to deadlines :D.
Also… “how Ruby and ROR are organized and structured in Fedora.”… they have a structure? I thought it was out of the box package management, without a structure or orga… like a “Mee too” as I never found any documentation specific for fedora…
By the way… ChatGPT has been my best friend… not Documentation.
Maybe we should be focusing on other “types” of documentation.
I agree completely with Peter here. Fedora Magazine is meant to be a place to promote FOSS software with quick and simple examples of the things it can do. The Fedora Docs site is a better place for a more detailed HowTo that might need updating from time to time. You can put content in both places, but if you do that I would recommend doing the more detailed Fedora Docs first and then just write a small demo of some sort for Fedora Magazine and then reference Fedora Docs as a place to get more detailed and more up-to-date information.
Well, that was exactly my way to get engaged in Fedora again. From my work, we had a lot of notes and guides to manage our servers - since the end of Scientific Linux Fedora only - and I planned for a long time to put it on a dedicated website. But never managed to follow through. And 5 years ago there was an initiative to improve maintenance of Fedora Server. And I somehow got the idea to contribute our notes and guides to Fedora Server Documentation. That was the birth of the dedicated Fedora Server documentation.
I mean the development workflow as it is underlying the standard installation. Where is what stored, where are vendor-specific program parts located? I could contribute more specific questions on this. I need to look at my notes. If I remember correctly, some parts are preconfigured specifically to Fedora.
We have a Fedora AI policy now. In short, preliminary work by AI is accepted, but it must be explicitly indicated, and the result must be checked manually.
Man… I don’t know who chose the tech stack the project is using for documentation… but what the heck
Document producers at enterprise level are usualy business analysts like me, not developers
Using GIT is weird, gitlab and no github is weirder, but ok… but asciiDOC? it is not enough to force newcomers to learn how to GIT, and you force them to learn another markup language?
Who thought of this thing? people like me come from JIRA and Confluence, with typical markup…
and then a Containerized app just to publish in HTML form?
…Gods…
Not even Omarchy goes to this level of complexification… Reason to DHH who mentions we became “Merchants of Complexity” on IT.
</ Venting >
Will try to read the documentation for creating documents by this weekend, and try to push something? is there a “branch” I can use to test? (will look for it)… But I will have to redo the complete docs for this ASCIIDOC and all my muscle memory.
Have fun!
If we don’t talk sooner, have a great Xmas holliday.
Push the modified clone to your fork created above
Create a Pull Request
It was not me. And yes, there is a lot critique about the stack. On the other hand it is at the top of current website technology, or at least of a branch.
well, using a asciidoc editor makes it a lot easier.
There is some additional docs, written for the Server working Group: User Documentation Maintenance :: Fedora Docs It’s basically the same, but a different wording and way to describe it.
WE are about to update and improve our Docs Team contribution documentation.
Enterprise documentation writers used to write stuff in docbook, which is XML
AsciiDoc syntax is very close to Markdown, but it provides a number of additional features, which make it more reliable when you need to validate and build larger multi-page documents.
You can see the use of :toc: feature in the example, which renders the table of contents in the document. Markdown doesn’t have that.
Admonitions (NOTE:,WARNING: and so on) is another example, which Markdown doesn’t have and which are extremely useful in the user documentation and how-tos.
While there is recommended editor mentioned above, most IDE’s or modern editors, GitHub and GitLab WebIDE included, can render asciidoc natively, so you don’t need to checkout or compile anything to preview the result.
?
