Installation instructions - consolidate the various different instruction and re-use a single common text file
mi-hol opened this issue · 5 comments
the best starting point for a single common text file seems to be openmediavault-docs/installation/index.rst but it requires clean-up (i.e. incorrect seems the statement "and several preconfigured images for ARM devices.")
different instructions exist on:
- https://www.openmediavault.org/?page_id=77 => note: source of page seems to exist outside of github
- https://openmediavault.readthedocs.io/en/5.x/new_user_guide/newuserguide.html#installing-on-single-board-computers-sbc-s
- https://openmediavault.readthedocs.io/en/5.x/new_user_guide/newuserguide.html#installing-on-i386-32-bit-platforms
- https://openmediavault.readthedocs.io/en/5.x/new_user_guide/newuserguide.html#amd64-64-bit-platforms
- forum?
Note: the list is likely incomplete! Please add links here as you find them
While I can't speak to the contents of the /installation/index.rst :
We've been over 2, 3 and 4 at length. 2 and 3 are scripted builds (OMV-Extra's), where 4 is the ISO build (main-project).
These documents are on their appropriate wiki's, in accordance with the division of the project along two separate areas of responsibility. Further, they all differ in significant and irreconcilable ways. They address different hardware platforms, they have different build processes, they may use different installation media, they have differing options, and different packages are installed by default. (Etc, etc). I honestly do not see a path to combining them, into a single document, that would not be extremely confusing to new users. Cross linking, at the appropriate locations, seems to be working well.
Investing more time and effort into 5.X maintenance, before archiving, seems wasteful at this point in time. When OVM6 comes out, in a few months, a significant rewrite and update will be required.
Well, what really matters is user experience and currently it is constrained by the division of responsibilities.
@votdev should we not try to improve the user experience for installation of OMV6?
Now would be the perfect time from my view.
How would you "improve" the user experience? Installing OMV on different systems is very different based on architecture. Hence the multiple guides. And keeping them separate based on architecture reduces the chance that people will do something meant for another architecture. You are trying to fix something that is not broken.
If we were talking about printed media, without hyperlinks, the "user experience" might be an issue. Given that the media is electronic, what difference does it make (to the user) if they scroll down to a new chapter or mouse click a cross link? Which, after the completion of an SBC or 32bit build, the build document ends with another cross link to bring users back to the appropriate place, to continue with the configuration of their build. All of the above is available, on the same screen, with "point and click" ease.
Just as it is in programming, a "modular" approach works well. Changes, updates, and other edits are confined to the affected document only. I imagine programming blocks are handled in a similar manner.
@votdev should we not try to improve the user experience for installation of OMV6?
Now would be the perfect time from my view.
Without seeing an alpha or a beta, there's no reference to begin. However, I suspect the amd64 build process, up to logon, would be nearly identical.
Apparently not achievable