nextcloud / nextcloud/whiteboard

[DOC] Ideas to improve the Documentation

Open
#1,342 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
215
Forks
39
Avg merge
1d 3h
Merged PRs (30d)
32

Description

I commented this point at #1225 . But that issue is about non technical users. This issue is about technical affine admins. So I made a separate issue on the Ideas here.
Following questions and notes arose to me during the study of the README.md:

  1. The repository is for the whiteboard app. But the Installation & Setup section only explains how to setup the collaboration function and the communication to the whiteboard collaboration server. May be a note about installing the app itself (app store) would help, and may be the section Installation & Setup should be renamed and divided into two sections "Installing the Whiteboard Collaboration Backend" and "Setup the Communication for Collaboration".
  2. Nothing is written about the configuration parameters max_file_size, disable_external_libraries, recording_auto_upload_on_disconnect and legacy_libraries_migrated.
  3. In the documentation the whiteboard server (product name) is sometimes called websocket server (technical description) or collaboration server. The occ parameter is called collabBackendUrl . May be it is better understandable to admins, if the whiteboard server is named more consitently - may be "whiteboard collaboration backend".
  4. A short note could explain, that the whiteboard collaboration backend" provides a websocket to communicate with the the Webbrowser(s).
  5. The URL to address the whiteboard collaboration server is https://..., but it is not described how to configure certificates. Are there (self signed) certificates provided with the whiteboard collaboration backend?
  6. For the proxy configuration (Apache, Nginx, Caddy) the url is http:/... .
    Does the whiteboard collaboration server can do both (http and https)?
    Does it support ws://... or wss://... or both?
  7. For the proxy configuration, only a ProxyPass (apache), location (nginx) or handle_path (caddy) entry is shown. It would be more clear if it is explicitely noted that the proxy configuration is made in the nextcloud (web) server configuration.
  8. All in all it would be helpful to have a communication diagram in the documentation to get a big picture. I could provide a communication diagram if I would understand how the communication flow is.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with README.md, especially the Installation & Setup and proxy configuration sections, and review the documented configuration parameters and communication terminology. Clarify which documentation changes are supported by the existing setup, including certificates, HTTP/WebSocket schemes, and proxy placement. Done means the installation, configuration, terminology, proxy guidance, and communication flow are documented consistently, with a diagram if the flow can be established.

Written by the indexing model from the issue text.

Assessment

Tech stack
nginx
Domain
devops, documentation, networking
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.