nextcloud / nextcloud/whiteboard
[DOC] Ideas to improve the Documentation
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:
- 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".
- Nothing is written about the configuration parameters max_file_size, disable_external_libraries, recording_auto_upload_on_disconnect and legacy_libraries_migrated.
- 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".
- A short note could explain, that the whiteboard collaboration backend" provides a websocket to communicate with the the Webbrowser(s).
- 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?
- 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? - 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.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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