Skip to content
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

Open
2 of 8 tasks
joshtrichards opened this issue Jan 17, 2024 · 4 comments
Open
2 of 8 tasks

Comments

@joshtrichards
Copy link
Member

joshtrichards commented Jan 17, 2024

Throughout the documentation there are repeated references to things like:

  • various filesystem paths
  • occ commands
  • various URLs for the reader to utilize
  • OS usernames / UIDs

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

  • Coming up with some standards for some of the most common items that fall into this category
  • Documenting a standard presentation that will be used as part of our "writing style" (in the README/similar)
  • Making it clear to the reader how to adapt the presentation to their own environment somehow (somehow and somewhere in the manual - the specifics need to be worked out)

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:

  • put this idea out there
  • settle on a couple initial items that seem like good candidates for this
  • discuss and identify the most common items in this category (comment if you think of one not noted above)
  • explore existing functionality/recommendations for doing things like this with our current documentation platform
  • come up with a standard way of presenting each item (one by one) both in terms of content and style [include the design team in this]
  • determine whether the presentation needs to be explained within the manual in some way [ditto]
  • document the standard way in the README (or, if necessary, an auxiliary document)
  • start replacing references incrementally with the new standard presentation

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.

@joshtrichards
Copy link
Member Author

Brainstorming

Filesystem paths

  • Are always stated relative to Nextcloud installation folder and therefore installation folder agnostic
    • e.g. whether Server is installed in /var/www/html or /home/joeuser/cloud.joeuser.com the references to the following are tall the same:
      • Default data directory path: /data
      • Main log file: /data/nextcloud.log
      • Main config file: /config/config.php
  • Where absolute paths are appropriate use them - e.g.
    • Non-default data directory path located outside the installation folder: /mnt/nas/nextcloud-data

Questions/concerns:

  • In the above proposed approach, don't like that paths on their own don't indicate whether they're relative or absolute. This makes it impossible to distinguish at a glance whether /mnt/nas/nextcloud-data is relative to the installation folder or an absolute path.
    • Needs further thinking

@tflidd
Copy link
Contributor

tflidd commented Mar 12, 2024

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.

@ChristophWurst
Copy link
Member

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

@ChristophWurst
Copy link
Member

occ commands

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants