RfC: port OMV documentation to a 'documentation-as-code' approach?

  • Triggered by this comment I'd like to propose a change on how documentation is created & maintained, resulting in a better experience for how users 'consume' it.


    A common issue for any detailed documentation is the limited time the potential readers have, resulting often into TL;DR


    How to resolve this dilemma is an open challenge for many projects.


    Current situation for OMV is an online manual and a separate (unlinked) repository with PDF documents covering the same topics but from a different angle and different content.


    Mozilla Foundation is now trying to address these challenges using a new MDN platform. Details to be found here.


    Questions:

    - what are the maintainer's views in the changed approach (not the tooling!!)

    omv 6.9.6-2 (Shaitan) on RPi CM4/4GB with 64bit Kernel 6.1.21-v8+

    2x 6TB 3.5'' HDDs (CMR) formatted with ext4 via 2port PCIe SATA card with ASM1061R chipset providing hardware supported RAID1


    omv 6.9.3-1 (Shaitan) on RPi4/4GB with 32bit Kernel 5.10.63 and WittyPi 3 V2 RTC HAT

    2x 3TB 3.5'' HDDs (CMR) formatted with ext4 in Icy Box IB-RD3662-C31 / hardware supported RAID1

    For Read/Write performance of SMB shares hosted on this hardware see forum here

    • Offizieller Beitrag

    omv 7.0-32 sandworm | 64 bit | 6.5 proxmox kernel

    plugins :: omvextrasorg 7.0 | kvm 7.0.9 | compose 7.0.9 | cputemp 7.0 | mergerfs 7.0.3


    omv-extras.org plugins source code and issue tracker - github


    Please try ctrl-shift-R and read this before posting a question.

    Please put your OMV system details in your signature.
    Please don't PM for support... Too many PMs!

  • votdev, well the focus from my view, should be to integrate the 'PDF documents covering the same topics but from a different angle and different content' into automation and the published help texts

    Any comments on this subject?

    omv 6.9.6-2 (Shaitan) on RPi CM4/4GB with 64bit Kernel 6.1.21-v8+

    2x 6TB 3.5'' HDDs (CMR) formatted with ext4 via 2port PCIe SATA card with ASM1061R chipset providing hardware supported RAID1


    omv 6.9.3-1 (Shaitan) on RPi4/4GB with 32bit Kernel 5.10.63 and WittyPi 3 V2 RTC HAT

    2x 3TB 3.5'' HDDs (CMR) formatted with ext4 in Icy Box IB-RD3662-C31 / hardware supported RAID1

    For Read/Write performance of SMB shares hosted on this hardware see forum here

    • Offizieller Beitrag

    Well, this goes back some years.

    When I first adopted OMV, I found the existing documentation to be terse and command line oriented, which was an interesting conundrum in that OMV focuses on an easy to use GUI. Further, it seemed to me that a very large number of OMV users were PC/Linux beginners who were often directed to OMV by articles, and out-of-date or incomplete "How-To's" on the Internet. (That created another can of worms when they came to the forum for support.)

    For new users of this type, the info on the wiki is inadequate - that's the bottom line. As a result, the forum was littered with questions on basic topics like "what file system should I use", "how to create a network share", etc., etc. Adding to that, there were a couple among the experienced forum users of that time who were completely dismissive and even over-the-top rude to new users with basic questions.

    If the base assumption was true, that roughly 1/2 or even a majority of OMV users are PC/Linux novices, a very different kind of documentation effort was needed. To get new users started, I opt'ed for a very narrow "walk-through" format, that would teach basic concepts, and the use of supporting utilities, while building a basic file server. (Teaching during the build is the perfect time to do it - users are motivated as they work toward the end product.) That effort required a document format that is different from wiki and, to get it done in a reasonable period of time, I needed to control it. That led to PDF's because it's a cross platform format and sites exist to translate the text into multiple languages.

    So, again as noted before, the documentation differences (format and approach) between the wiki and the PDF's are due to differing target audiences. I'd be willing to merge the existing PDF's into a wiki format and relinquish control, but I don't think the information in the wiki and the PDF's could be "reconciled" into a single document. The two are apples and oranges.

  • crashtest, I appreciate the great documentation you created and the many hours you contributed to the OMV community!


    I wanted to provide feedback on where I'd see opportunities to improve it further though and offer to contribute a bit of my free time too..


    Well, this goes back some years.

    When I first adopted OMV, I found the existing documentation to be terse and command line oriented, which was an interesting conundrum in that OMV focuses on an easy to use GUI.

    Well I started my OMV journey back in Feb 2020 in exactly the same bad way :(

    A reason appears to be the missing "installation" section in

    https://github.com/openmediavault/openmediavault/README.md

    GitHub (GH) recommends an "installation" section is a best practice and from my own experience it helps new users a lot!


    For new users of this type, the info on the wiki is inadequate - that's the bottom line.

    I couldn't agree more :)

    a majority of OMV users are PC/Linux novices, a very different kind of documentation effort was needed. To get new users started, I opt'ed for a very narrow "walk-through" format,

    Since OMV is available on RPi and the availability of RPi4 with enough IO bandwidth for an entry-level NAS, I'd see the number of novices even further rising.

    RPi as entry-level NAS is the reason for me exploring OMV. I build a NAS for me and gave the identical solution to a friend not having any Linux skills. He is now the "guinea pig" for administrative tasks

    Teaching during the build is the perfect time to do it - users are motivated as they work toward the end product

    I'd agree too but there is the approach to work incrementally towards the final product too. In my case over 6 months after the initial build I wanted to add features and thats where I failed to find a link from the basic wiki to the more appropriate section in the PDF


    From my view this issue could be addressed by the following changes:


    - integrate all documentation into the OMV main git repository as this is the place users familiar with GH will look at first

    - convert the 'HowTo" PDF to markdown and split it into section matching with OMV GUI & wiki content

    - link wiki with new 'HowTo" content

    - apply available document creation automation to create the full 'Install Guide' as PDF too


    To see if the proposal will address your very valid concerns

    - perform a pilot project for one topic (i.e. Rsync)

    - try the new MDN process when it has matured a bit as it seems a major step forward for automated translation too


    I'm happy to talk about more details in a 1:1


    Looking forward to your comments :)

    omv 6.9.6-2 (Shaitan) on RPi CM4/4GB with 64bit Kernel 6.1.21-v8+

    2x 6TB 3.5'' HDDs (CMR) formatted with ext4 via 2port PCIe SATA card with ASM1061R chipset providing hardware supported RAID1


    omv 6.9.3-1 (Shaitan) on RPi4/4GB with 32bit Kernel 5.10.63 and WittyPi 3 V2 RTC HAT

    2x 3TB 3.5'' HDDs (CMR) formatted with ext4 in Icy Box IB-RD3662-C31 / hardware supported RAID1

    For Read/Write performance of SMB shares hosted on this hardware see forum here

    • Offizieller Beitrag

    Let's see if I can add some confusion to any clarity you may have. ;)

    I'd agree too but there is the approach to work incrementally towards the final product too. In my case over 6 months after the initial build I wanted to add features and thats where I failed to find a link from the basic wiki to the more appropriate section in the PDF


    I understand what you're getting at, which seems to be providing cross links to documentation at appropriate locations in the OMV Home Page, at download locations, and in the wiki. Bottom line - I don't have access to do that.
     
    I can add links to the wiki, in the PDF documents. That much I can do.

    For background:
    The original goal of the New User Guide was to address a very large user cross section of begineers and intermediate users, "inclusively'.
    I could go into that farther into that but, suffice it to say, the User Guide was almost exclusively about setting up and configuring OMV in the GUI.
    __________________________________________________________________________________________


    Regarding Rsync:
    Rsync was one of the few exceptions that was off the core topic of OMV. The only reason the Rsync command lines were included in the User Guide was to introduce users to the concept and a method for "full data backup" and to provide a simple method for full restoration. Why? Backup is important and is often ignored, especially by new users. Further, restoration is as important as the backup itself, so all of the needed details were provided in a beginner format, if they're reasonably attentive. But note, the data backup section doesn't go into any detail about what Rsync "is", just how to use it in a very specific way, within OMV's GUI.

    With the above noted, you're welcome to do so if you chose, but I wouldn't make a project out of Rsync. (Your call.) There are plenty of good Rsync tutorials out there. The best and easiest approach might be to explain what Rsync is, in simple terms, maybe provide a brief overview of what it does, then link to a good tutorial. There's little point in duplicating effort.

    Finally, other than writing the barest of "How-To's", realize that getting into any software package, in any depth, is analogous to writing a small text book. (Note that "Getting Started with OMV", is +80 pages.)
    ____________________________________________________________________________________________

    Also worth mentioning is, what I've been doing is unofficial. If not for ryecoaaron offering to host the build doc's and User's Guides, within his GitHub project, they would still be at mediafire.

    Regardless of where they're hosted, I see the existing PDF doc's as community property and they're annotated as such. My name is nowhere in them and they're available to whoever wants them. On the other hand, if the doc's are ported into a wiki, they need maintenance to insure that the reference links work, that they're updated as needed, and that build changes (4 types) are taken into account. ((Build changes are tested, more than once, to insure that results are repeatable.)) Anytime I edit one of them, I try to skim the remainder of the doc for clarity and relevance which usually results in a minor edit or two. It would be difficult to maintain these doc's, in such a manner, if a pull request is required in each and every edit instance.


    (So)
    I added my little contribution in PDF form and it seems to have been successful. Simple questions on the forum have dropped or may be referred to the User Guide, so it appears to be doing it's job. Setting aside temporary repo problems; feedback or complaints on SBC's and 32bit builds are very rare which means ryecoaaron's install script is working well, the doc's are easy to understand and doing their job. If document accesses are any measure, OMV is quite popular with SBC builds proceeding at a robust pace. -> traffic


    I suppose it all boils down to, "one does what one can".

  • OMV is quite popular with SBC builds proceeding at a robust pace. -> traffic

    crashtest when I click the provided link it doesn't appear to show the intended stats, but just my personal stuff.

    Would you mind to embed a screenshot of the stats?

    omv 6.9.6-2 (Shaitan) on RPi CM4/4GB with 64bit Kernel 6.1.21-v8+

    2x 6TB 3.5'' HDDs (CMR) formatted with ext4 via 2port PCIe SATA card with ASM1061R chipset providing hardware supported RAID1


    omv 6.9.3-1 (Shaitan) on RPi4/4GB with 32bit Kernel 5.10.63 and WittyPi 3 V2 RTC HAT

    2x 3TB 3.5'' HDDs (CMR) formatted with ext4 in Icy Box IB-RD3662-C31 / hardware supported RAID1

    For Read/Write performance of SMB shares hosted on this hardware see forum here

    • Offizieller Beitrag

    One effect of locating doc's on Git-Hub is, "they get around". I've looked through some of the referring sites, from time to time, and have found project related articles where some or all of OMV's build processes is translated into another language. I've also found youtube How-To videos that are very closely based on the doc's, with a few linking a doc to their videos. That is EXACTLY what is desired. From a forum support standpoint, there's at least a rough understanding of the user's basic build to work from, when a beginner comes to forum for support. (As an example, if they follow the doc's, users won't install a Desktop or they're at least warned of the potential consequences.)

    BTW: I wasn't trying to discourage you from producing new content, but it makes sense to try to limit the majority of the content to the features available in OMV and it's plug-in's. As an example; I started something for SNAPRAID and Mergerfs, as a RAID5 substitute for home users and, potentially, SBC users.. It would be a "walk through", primarily, but at least an overview explanation of the relevant features in each package would be needed. (Again, the focus would be beginners and, to some degree, intermediate users.) I set it aside for the winter months where more time would be available.

    2 week stat's herewith:







    • Offizieller Beitrag

    I started something for SNAPRAID and Mergerfs, as a RAID5 substitute for home users and, potentially, SBC users.

    I’m looking forward to this one.


    From a consumer stand point I prefer the pdf because I can download and store it in my “toolbox” folder of guides. Keeping a bookmark of a wiki page or pages seems more problematic, for me anyway. There is the editing and revising task, but that exists either way, and either way can become out of date without revision.

    • Offizieller Beitrag

    From a consumer stand point I prefer the pdf because I can download and store it in my “toolbox” folder of guides. Keeping a bookmark of a wiki page or pages seems more problematic, for me anyway.

    Noted. There's more than one group that would fit this category. Off-line users, such as small businesses, who are not connected to the net would benefit from "owning" a fixed downloaded version. Further, users who may not upgrade OMV frequently, can retain their applicable version. The current process forces users to download the version that applies to their ISO, image, etc.

    There is the editing and revising task, but that exists either way, and either way can become out of date without revision.

    We're having an off-line conversation along those exact lines. While minor edits are not accounted for, I've been dating significant updates as they're done. Without maintenance, particularly with doc's of this type, they become outdated quickly.
    (We're not talking about something like Linux man pages with years between updates, if ever.)

  • - apply available document creation automation to create the full 'Install Guide' as PDF too


    From a consumer stand point I prefer the pdf

    Agricola the proposal considered that, so no worries. The goal of the proposal is basically to re-use content that was created & maintained once, for several different purposes and formats, hence it should lead to an even better user experience

    omv 6.9.6-2 (Shaitan) on RPi CM4/4GB with 64bit Kernel 6.1.21-v8+

    2x 6TB 3.5'' HDDs (CMR) formatted with ext4 via 2port PCIe SATA card with ASM1061R chipset providing hardware supported RAID1


    omv 6.9.3-1 (Shaitan) on RPi4/4GB with 32bit Kernel 5.10.63 and WittyPi 3 V2 RTC HAT

    2x 3TB 3.5'' HDDs (CMR) formatted with ext4 in Icy Box IB-RD3662-C31 / hardware supported RAID1

    For Read/Write performance of SMB shares hosted on this hardware see forum here

Jetzt mitmachen!

Sie haben noch kein Benutzerkonto auf unserer Seite? Registrieren Sie sich kostenlos und nehmen Sie an unserer Community teil!