-
Notifications
You must be signed in to change notification settings - Fork 1.6k
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
Standardizing commonly referenced strings throughout the documentation #11447
Comments
BrainstormingFilesystem paths
Questions/concerns:
|
Question regarding this, could we have a app that provides this information. On the forum we spend quite a lot of time to guide people what their webserver user is, where the data folder or config folder is located. From within Nextcloud, this should be relatively easy (not sure about the containers). Not sure if it is possible, but if you have a json object with all the parameters, you could just copy&paste this to the docs-webpage, and then all the paths are fixed to work in your environment. |
@tflidd sounds like a great idea. I know this from services like Sentry and Blackfire, where you have API keys in the getting started documentation that is actually your API key. Neat, but I'm not sure how we could bring this into Nextcloud. If anything, it would only work for the inline version of the docs packaged with Nextcloud. It would not work for the online version at docs.nextcloud.com. |
This is slightly off-topic but what I would like to see is that we have a central page for occ explaining what it is and how it works but move the commands to pages that fit the topic. For example there are twofactorauth commands in https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/occ_command.html that should be at https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/two_factor-auth.html. |
Throughout the documentation there are repeated references to things like:
occ
commandsThese generally (or at least often) vary in different installations/environments (e.g. the folder Nextcloud Server is installed in, nuances of syntax for executing
occ
based on install/runtime method and file/process ownership).Sometimes these references are made without the proper context for the reader to realize they need to be adapted to their local environment. In other cases some context is provided, but it's inconsistent with how similar references are presented elsewhere in the same manual.
This creates an additional burden on the reader. It also creates a burden on the writer, which has to decide what - if any - context to provide each time. And these inconsistent references become a pain in the butt to monitor/maintain/refine (since making updates is not a simple "search and replace" throughout the manual).
I propose we make this better by:
This mostly applies to the Admin Manual (and to a lesser extent the User Manual).
The initial tasks I've come up with so far:
If we decide to get fancy we could even have dynamically adjusted values (with reasonable defaults), but that's putting the proverbial cart before the horse. Let's figure what and how we want to present things first IMO.
The text was updated successfully, but these errors were encountered: