Improving community documentation for non-enterprise users

[sunjam]

I've noticed that current documentation puts burden on employees and contributers in that:

• Certain articles must be withheld for clients, especially enterprise. This is understandable.
• Documentation is managed through github, which means each edit must be approved by employees.
• There is no clear community documentation available outside of either company maintained documentation or within the forum at https://help.nextcloud.com, with the closest thing to community docs being a howto section, which is restricted to contributions to longer term users. For whatever reason it doesn't feel the same as a normal documentation site, both in presentation and use...
• The process of tracking and reporting to Github is awesome to offer to the wider community, but it isn't the same as clear documentation. As-is, it requires a lot of on-boarding on the part of the user as the gradually learn where to look for which app/server/client/etc.

I think it is worth considering how to improve documentation for small installations. Let me totally rephrase this request:

Is there a way to improve documentation, while lowering employee overhead, so that small user admins experimenting with things like clustering and multi-server setups can write up documentation together without stepping on your existing enterprise support? This isn't related to any interest in large scale deployments, but the existing documentation is notably missing articles which would help the casual admin. For a reference, I want to encourage you to look at Ubuntu, which has official documentation from Canonical, but even more importantly they offer absolutely rich community docs outside of the "official" docs. Arch Wiki is not a company, but I love how it answers all casual admin questions you would otherwise need to post to a forum about, so I love the thought of finding something closer to this in regards to answering common Nextcloud questions. Cheers.

Thanks for any consideration and thoughtful discussion.

[jospoortvliet]

Pfff, tough question. I mean, the how-to section in the forms that you point to was kind of meant for this purpose. A wiki could also be set up, but that means maintaining another piece of infra. What doesn't work for you about the forums in this regards? It has a list of articles, it has a good search... It works for me when I search for stuff for my own server but of course I'm just one random user 🙈 Anything we could change there?

[DaphneMuller]

Thank you for your constructive feedback and for starting an interesting discussion how we can improve. We understand documentation is important for the success of any installation and we agree that there must be ways to improve in this area.

Documentation is managed through github, which means each edit must be approved by employees.

with the closest thing to community docs being a howto section, which is restricted to contributions to longer term users. For whatever reason it doesn't feel the same as a normal documentation site, both in presentation and use...

So there are multiple options to improve I see, through potentially finding ways to make editing the GitHub-documentation more accessible for non-employees, or through adjusting the medium of the how-to section in the forum.

Could you give more details on why you feel the how-to section is a limited experience? Its advantages are that it's a channel with already a good user base, some form of a trust-system is built in, and its easy to search its content and also findable through search engines. But maybe other alternatives exist that would be better, like a dedicated wiki system such as collectives. Also for the GitHub documentation, we started some months ago with a PR-feedback-bot, so on every pull request a bot posts a message (after 2 weeks) asking if the contributor is happy with their reviewing process, so if a pr is not reviewed they can easily reach out to me. This should have reduced the barrier to entry to some extent. Edit: another issue I see with GitHub is that it is not very accessible to non-developers, so it reduces the potential size of the community who could contribute. Especially to the user-documentation. Probably admins are comfortable with GitHub.

[tflidd]

• Documentation is managed through github, which means each edit must be approved by employees

It is not just employees, not sure if you need to count as contributor which applies for more people (some app developers and community people like myself). The structure is a bit fix, reviews and approval can take some time, ... it's not perfect.

• https://help.nextcloud.com, with the closest thing to community docs being a howto section, which is restricted to contributions to longer term users.

It was not supposed to exclude people. There are a lot of community contributions and normal posts can be converted and moved to this section. The moderators can help you with that. The purpose of the howto section is then that it can be edited by more people to keep it updated.

Perhaps there are better ways to organize howtos and tutorials that are easier to start with... Do you have a project in mind where you think the documentation works great (especially for the community)?

[sunjam]

Asking around for others to give their input here and got this dm:

I agree tutorial-like docs following same structure more or less up-to-date living in this forum would be appreciated. Wiki category is low-level entry and good fit in my eyes maybe we should promote and write more articles here?

Do you have a project in mind where you think the documentation works great (especially for the community)?

Well, I do think using the forum has been great for keeping community maintained documentation served as https://docs.nextcloudpi.com

[sunjam]

another issue I see with GitHub is that it is not very accessible to non-developers, so it reduces the potential size of the community who could contribute. Especially to the user-documentation. Probably admins are comfortable with GitHub.

This is very true, especially for trying to flesh out documentation to include more apps and more use cases. But even if articles were written elsewhere they might prove useful enough to submit back to github for primary documentation...

It is not just employees, not sure if you need to count as contributor which applies for more people (some app developers and community people like myself). The structure is a bit fix, reviews and approval can take some time, ... it's not perfect.

Okay, corrected that others also manage github docs

Perhaps there are better ways to organize howtos and tutorials that are easier to start with...

Howto's are fine, but there is far more to Nextcloud documentation than individual howto's. I think hints lie in the issues on Github or the forum that get answered again and again. Heck, perhaps some of those write ups could be linked / quoted into some documentation.

The purpose of the howto section is then that it can be edited by more people to keep it updated.

I think the current howto section (most people are likely not aware of it) and Github documentation are not lowering the barrier of entry near enough... but, I also think think people can be trusted more than they are given credit for.

• Howto section is not organized at all afaik and limited to forum users Trust Level 2, which is difficult to get. A real index that is easy to navigate and includes all articles.
• There is a total disconnect from howto and github docs
• Disconnect between outside App developers of hundreds of apps and existing docs

[JimmyKater]

as a first idea...

• how would expect the "how to" category of the forum to be the place to look for documentation? At least not me (though it makes sense to do so).
• so why don't we just rename that section to "(community) documentation?

And then... as there are some additonal documentations available there on GH (or such) why don't we demand app-devs (at least) to upload them to some extra space under new category "documentation/apps/3rdparty" and either just have a 1:1 copy there or the original documentation? we even could set up a special "Documentation"-button under apps.nextcloud.com under the "interact"-section

[sunjam]

either just have a 1:1 copy there or the original documentation? we even could set up a special "Documentation"-button under apps.nextcloud.com under the "interact"-section

But doesn't that inherit the same problem of someone needing to get the documentation approved, when they would rather publish and move on (as you would in your own repo)

edit: wondering if the 1:1 mirror concept would work

[JimmyKater]

well I dunno what exactly is wanted and why it is as it is... but it wouldn't change anything except that we would have a place at the froum where you'd have all documentations for apps, if they'd provide such a document as a starting point.

So we could add more community documentations exactly there... maybe the 2nd place where you would look after the official manual.

[sunjam]

Moving here from dm I received...

I’m following the discussion on github and I’m surprised people from the company are more or less responsive there. but in general I don’t know how to achieve the goal.

Nextcloud’s documentation suffer at the same point like many other products. there is a list of possible config options but there is no good description how to link them together to a working system and what to add and how to master things besides NC - which is in my eyes the hardest part for many users and where we can’t expect lot of support from core developers and from the company. It doesn’t become easier as dozens of possible supported and valid installation variants exist… all of them require little different approach.

I general I share the point of view such docs should live in this forum as :bookmark_tabs: How to or Wiki (btw I suggest to merge both categories) the question is how to get rid of old outdated articles and gather fresh high-quality content. I made an article for Nextcloud Collabora integration which explains the basics and provides some troubleshooting steps - with this article I feel the threads regarding this topic improved a lot. I think if we could provide more of such articles this would be huge improvement but I don’t know how we could motivate enough qualified writers…

[isdnfan]

sunjam already posted most important point from our direct forum chat above - the main point in my eyes is not the place where the improved doc should live but rather how improve the content. Nextcloud has many dependencies to other products like database or webserver, often it runs behind reverse proxy - one of the most demanded topics in the help forum and very bad documented. no good official docs exists about "how" to run the whole system, what is the best way to integrate with related products. same applies to apps - even "official" apps have their docs and bug tracker separated from the main project.

Definitely such How-To articles maybe little misplaced within main doc repository and there are good reasons not to treat them as "Docs" at all. But the initial write up should come from the dev and might be there should must more demand from the core team on everybody to create such article. Good example is user_oidc article from schiessle - basics are explained and for details one can reach out to the forum and more detailed docs. I would really appreciate much more of such articles would exists in one place providing a starting point for every question.

But I see the limits as well - how one could expect the core devs to write background articles when important ~community~ user needs are not addressed for ages? e.g https://github.com/nextcloud/desktop/issues/5302

[sunjam]

But I see the limits as well - how one could expect the core devs to write background articles when important ~community~ user needs are not addressed for ages? e.g nextcloud/desktop#5302

Exactly, it is not possible to ask the core devs to maintain more documentation, or to even have time to manage the existing 95 submissions.

A solution would be to address documentation that can be community maintained, while also publicly visible. People in this discussion understand a place like the how-to section, but they also understand almost every facet of Nextcloud itself.

Here is what comes to mind currently:

• Official docs
• How-to and other categories on forum
• Github and whatever other version control repos being used by hundreds of third party apps
• apps.nextcloud.com
• Documentation, repos and communities of other projects modularly used alongside Nextcloud (apache, nginx, list goes on)

To even stitch these things together more closely would be amazing.

[sunjam]

Coming back to this, since we are discussing the 30 release and confusion in regards to steps needed to access the newly announced functionality once an admin has updated to 30. Specifically:

• Flow
• Nextcloud Assistant
• Text Translation

In that discussion thread we work out where to find more information.

[DaphneMuller]

Coming back to this, since we are discussing the 30 release and confusion in regards to steps needed to access the newly announced functionality once an admin has updated to 30. Specifically:

* Flow

* Nextcloud Assistant

* Text Translation

In that discussion thread we work out where to find more information.

Assistant, incl translation: https://docs.nextcloud.com/server/latest/admin_manual/ai/app_assistant.html

Flow: https://docs.nextcloud.com/server/latest/admin_manual/file_workflows/index.html and in the readme: https://apps.nextcloud.com/apps/flow

[isdnfan]

Assistant, incl translation: https://docs.nextcloud.com/server/latest/admin_manual/ai/app_assistant.html

this shows the problem very well - throwing a list of config options on the user without meaningful explanation and recipe how to get it running (especially on appliances like Docker, AiO snap NCP) does not address the problem. Look at https://zitadel.com/docs/guides/integrate/services as very good documentation showing how the application works together with other components of the whole system.

At the moment Nextcloud docs are very cluttered and don't follow any (visible) concept. e.g. Office docs are very very verbose about reverse proxy integration https://docs.nextcloud.com/server/latest/admin_manual/office/proxy.html while the "normal" docs is very hard to understand https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html