-
Notifications
You must be signed in to change notification settings - Fork 51
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Populate File Servers page with links to outside docs on how to use ?? #431
Comments
Many thanks for your suggestion.
I second that. Generally contributions/additions by using e.g. another tab like "Access from macOS", or another section in the "Client setup" (or similar) are welcome, to have our docs more complete in this regards.
Especially I often find a lot of very outdated documentations for various things. It's a bit the nature of open protocols and FOSS solutions, as often the server platform is developed by one team while various clients and extensions are developed by other teams, some then not maintained anymore etc. From the end-user perspective, a single provider, which reliably develops and maintains documentation for server, clients (for all platforms), a plugin database/market etc, is much easier, which makes G***** etc such an easy choice.
True and one of the major aims of DietPi. Also for experienced Linux users/admins it can be a time saver, but someone with enough experience can do all the things manually from the console, or via own scripts, and customise it better towards own needs without using any DietPi script. So naturally and by intention we aim to make is easy for lesser experienced Linux users to setup any sort of own server.
It's a question of man power for writing/extending docs and especially also maintaining/updating them. IMO nothing is worse than documentation that is simply not true anymore, causing failing/insecure/etc setups and headache, when one thinks that it must be working as the guide was followed exactly. But I think it's good to have basic install/setup/update notes covered in our docs so that users can start using software we provide via We start to more consequently link official docs and resources below our docs sections, see e.g. here for rTorrent + it's ruTorrent web interface: https://github.com/MichaIng/DietPi-Docs/pull/424/files#diff-37d0be02b608c022bc4a4ab9d10542c0d75b6b34797492cad08e81033ce8dab3R262-R272 Important is also to make clear, in case, the aspects of our particular software implementation. Most software comes moreless with an executable, or even the source code only, and sometimes with an implementation suggestion but few strict rules or needs. Where the application data is stored, where the config file, the content of the default config file, listening port etc, the service manage that invokes it, how to access its logs, service hardening/sandboxing, which UNIX user is running it, permissions for that user, whether a DEB package is used, a single pre-compiled binary or a source build on install... All that cannot be derived or known from the official docs. This flexibility most UNIX software serves has up- and downsides, but it means that implementation aspects must be part of the distros documentation, maintained by the distro itself. That is often also the bases to e.g. setup clients: Which network protocol, IP, port and default credentials does one need to enter into the client to access the server that was freshly installed via |
Yes this is really top of mind to me. "Everyone wants to build, but nobody wants to maintain." Maybe better to lean towards less documentation which will be more manageable long term.
So if I understand properly, you are not in favour of linking to outside resources for information on how to use client-side software?
I think linking to official docs for all the included packages would be good. I see that some places this is done but not everywhere. In #412 you were talking about standardizing the tabs. Would it make sense to make a tab for links to official docs, forum, wiki, mailing list, subreddits, repos etc? The reason I wasn't sure about this is because I am not sure what changes were made when DietPi was put together. Like maybe the information in the main docs would be incorrect, or require clarification, in the context of DietPi. If that's not the case then I can work on getting the links together if desired. But if not that's cool! I just wanted to help and easy things are the only things I know. ;) |
I mean that a good balance needs to be found and probably documented (meta) as well as kinda contribution guideline, as this was never discussed explicitly, which it should:
Aside of the above, I agree that detailed instructions that include certain UI features or config file settings, should be kept at a minimum, as both can change and would need to be kept updated. Especially if good official docs or a manpage exists, it makes sense to link this instead, and, if we think those lack info, we could contribute to the official docs directly to benefit everyone.
The docs initially were moreless copy&pasted from the forum. The idea to add links to official website/docs etc came later but is now consequently followed and added gradually, not inside a tab but allow the tabs as it is done currently. If you want to help speeding up this task, I'd appreciate that very much 🙂. Coincidentally we just recognised that long link lists below each software doc section start to look a bit bad and thought about a way to make longer lists look better, either to move them into a tab (not good IMO), into a table or HTML list (better IMO). A table with a fixed set of single-line info is actually a good idea IMO, which could contain the software ID and other info from the Wiki list: https://github.com/MichaIng/DietPi/wiki/DietPi-Software-list |
So as to linking to each package's existing official docs, are you thinking it's better to make one big table with everything in it like the link in the wiki? |
@CouldBeThis: First of all: Yesssss. I appreciate your support and your ideas. Generally, I think you are right on track with your ideas, they more or less perfect fit to what we are doing now. Like software, we also always think about refactoring our doc structure (like how to handle more and more links to the outside). Back to the details of the file server pages: IMHO, adding more informations about other OSes would be perfect. The structuring with the tabs seems not to be 100% ideal, so let's also work on this (generalization, harmonization). One more option, which we are actually started, are HowTos for special purposes: See there. |
Thank you I appreciate. :) I think the best thing for me would be to start making small changes to get the hang of this because I have never participated in a project like this. Get some more practice with commits. But it seems like there are a number of structural questions arising in various issues. Is that what you mean by "refactor"? It would make sense to have an idea in what direction this is heading. I would be interested to see what others have done in similar situation. Do we know of any documentation for similar projects? Raspberian comes to mind: [quite straightforward docs]. Though that's just one section of the larger Pi docs. I support more instructional type content in here. To be honest in general it is quite sparse for me. Only time afforded by covid has allowed the luxury of taking the scenic route. I don't know if they are here also, but the person who posts on the forum as Joulinar looks to have done a great deal of writing, basically whipping up custom tutorials for various users asking for help. I wonder if it would be possible to collect "greatest hits" of forum writing, maybe by soliciting from users. Tidy it up a bit. Is there much communication between this repo and that forum? |
Jep @Joulinar write indeed a few great smaller and larger HowTo's in the forum. We generally move/moved stuffs from the forum to the docs, but not that systematically, so there are still lots of great hints/infos/tutorials in the forum that would fit into the docs as well. Generally a good idea would be to encourage users, who write things like that in the forum, especially in the "Community Tutorials" subforum, to contribute this to the docs either additionally or directly, which IMO has many benefits over the forum for instructions, e.g. search-ability, readability and style. |
Usually these how-to are specific for dedicated user situation. There are a couple of more general one like the how-to for setting up HTTPS on Nextcloud. But not that much. |
I remember quite a few cases where we linked instructions from the forum on GitHub or within the forum. Sometimes with small changes they can be generalised as well. At least it is worth to have a look into the forum when writing new docs content, as it may contain some nice instructions always, or aspects that we a good addition or so 🙂. |
Since I have learned that this repo welcomes contributions, I am touching up the file servers page as I am trying to get some method of file exchange running. Since there is already some Windows specific instruction for how to access the different servers, it seemed reasonable to add for other major platforms: Mac, Linux, Android and iOS.
Motivations:
But there is no reason to turn this into "how to use FTP" etc. So I thought instead to find appropriate tutorials elsewhere and link them. What I am looking for is the most minimal, generic, clear information I can find. Ideally would be one text and one video, but I am only looking for text right now. (And ideally in different languages.)
I am wondering what the maintainers of the repo think of this?
Pros:
Cons
If others support the idea, then it might be worthwhile requesting suggestions and/or review of links from the forum.
The text was updated successfully, but these errors were encountered: