Populate File Servers page with links to outside docs on how to use ??

[CouldBeThis]

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:

• Having ready access to usage information can save a lot of trial-and-error. It is more likely a person will be able to select the correct tool for their case to begin with.
• Hopefully quality docs can be located to point people in a good direction. After spending time this morning looking for these, I can tell you they are not necessarily easy to find.
• Since this distro is branded as one of the easier ones to get going with, it is reasonable to assume people with incomplete knowledge will be using it.

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:

• Don't have to write original materials on topics that are well elaborated elsewhere
• Keep the dietpi docs focused on dietpi; avoid filling up oodles of space with ancillary materials

Cons

• Outside documents might be for slightly different use cases + therefor introduce confusion
• Might change or disappear (but could link to archive.org versions to mitigate)
• I have a Mac so while I can look for tutorials for the other OSes I can't test them.

If others support the idea, then it might be worthwhile requesting suggestions and/or review of links from the forum.

[MichaIng]

Many thanks for your suggestion.

it seemed reasonable to add for other major platforms: Mac, Linux, Android and iOS.

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.

Hopefully quality docs can be located to point people in a good direction. After spending time this morning looking for these, I can tell you they are not necessarily easy to find.

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.

Since this distro is branded as one of the easier ones to get going with, it is reasonable to assume people with incomplete knowledge will be using it.

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.

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.)

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 dietpi-software without the need to check external docs. How to connect with clients from all major platforms to the installed server software belongs to that IMO. How to adjust/tune features and performance aspects, use additional plugins/modules und such probably not, where linking external, at best official docs is a good idea.

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 dietpi-software. Where to find and how to install the client on different platforms is then more a little note for completeness, which most users will figure out anyway for their major desktop or mobile platform.

[CouldBeThis]

It's a question of man power for writing/extending docs and especially also maintaining/updating them.

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.

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 dietpi-software without the need to check external docs. How to connect with clients from all major platforms to the installed server software belongs to that IMO.

So if I understand properly, you are not in favour of linking to outside resources for information on how to use client-side software?

How to adjust/tune features and performance aspects, use additional plugins/modules und such probably not, where linking external, at best official docs is a good idea.

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. ;)

[MichaIng]

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 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:

• All implementation-specific info can only be part of our docs. Such can naturally not be known by the software developer but is info that the distro needs to provide. This covers actually most of the info that our docs contain, currently, e.g. how (on which port) to access web interfaces/APIs, which directories are used, how to view logs, how to update the software, and in some cases one needs to setup e.g. database access on first access, which depends on the database name, user and password that we usually create as part of the install.
• Furthermore a slim quick access/setup instruction IMO is good to have, so just the very most important things to start with. This includes client setup (which again depends on mention network port/API/credentials info) and things like adding media directories to the software library, which also is part of our implementation of the /mnt/dietpi_userdata/(Music|Video|Photos|downloads) dirs. Those in most cases the quick start instructions are tied to our specific implementation as well.

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.

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 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

[CouldBeThis]

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?

[StephanStS]

@CouldBeThis: First of all: Yesssss. I appreciate your support and your ideas.
Like Micha mentioned, we just added the linking outside to the places where they belong to. Otherwise we need to structure the "big table" and jump to the relevant section from the software title description. In this issue it's a good place to talk about these options.

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).
So therefore I would like to encurage you to add things. I like also offer to support you with the structuring, editing, etc., if needed (also outside of these issues via private mails).

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. There we have to balance between writing own documentation and linking.
And we have to learn how many entries are not too much... Otherwise we will restrucure it. :-)

[CouldBeThis]

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?

[MichaIng]

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.

[Joulinar]

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.

[MichaIng]

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 🙂.