Requirements for a new documentation platform

[DKX47]

Continuing the discussion from the ncp wiki team telegram group here.

Looking at the current documentation there is a certain interest, to evaluate other platforms for documentation.

Some requirements from the telegram group:

• better formatting for code / commands, currently commands like "$ docker ps -a" are handled with line breaks or with quotes like “sudo reboot now" which is hard to read and makes it difficult to highlight console output. See also this issue

• multiple language support / translations

• multiple users and/or groups (probably with different rights)

personally I would add:

• good navigation through different entries (sidebar, topbar or menu etc.)

So, lets discuss :)

[ovpc]

What are you (or anyone else) suggesting, to do, to meet proposed requirements? Apart from the Theme and code formatting, Wordpress already meets all mentioned requirements, it is why it was chosen. (we are looking for assistance from creator of Buddypress, to resolve the coding issue) I can only think of one platform that might exceed WP's versatility: Drupal. Unfortunately not my cup of tea. I'm an old WP dog, and dont learn new tricks that easily anymore, nor do I aspire to ;-) I am glad to see new interest in ncp documentation, and willingness to contribute, anything that advances NCP's cause; making NC easier to set up and maintain.

And if someone wants to port NCP's docs to another better suited platform, they are familiar with, set it up and manage it, that's very fine by me.

[sunjam]

I think the coding issue is totally resolvable.

Aside from the current platform, what makes the most sense afaik is to use the actual help forum. We could create a documentation section on the help forum with write access for private group members of NextcloudPi so it is easy for us to maintain. Give all other forum users and guests read access, or just the ability to comment. Could also make certain posts, such as supported devices, publicly wiki editable so others can help us maintain them.

Main thing I like about this possibility is it integrates that much deeper into the Nextcloud community, plus greatly simplifies that amount of work needed to maintain documentation. Awaiting approval on a post is not my favorite, but people could always write up docs on the forum and then have a moderator move them into NextcloudPi doc group (if weren't otherwise adding said person into the group to grant them write permissions).

Just another possibility.

[ovpc]

it integrates that much deeper into the Nextcloud community, plus greatly simplifies that amount of work needed to maintain documentation good point, agree, we'd only lose the (manageability of) translations, although I must say: nothing much is and has been going on in that aspect. Most users manage in English apparently, so it seems.

[DKX47]

Just to give you some impressions of what I like looking at other CMS for purpose of documentation:

An expandable, nested navigation bar

Predefined formatting for things like warning, info etc.

But I don't want to solve a problem that doesnt exist, so if wordpress is the way to go I'm fine with that :+1:

Using the nc forum for deeper integration into the community seems reasonable. Personally I never got used to the structure, like using a kind of a tag system instead of a sub forums etc.

[theCalcaholic]

I'm pretty sure that all of that is solvable in Wordpress as well. I'd rather adjust the current documentation than go through the effort of setting up a new solution and migrating all the content and users.

I think it's better to collect a list of desired features and add them to the wordpress page.

[nachoparker]

actually our first solution was readthedocs, but it didn't have good language support

[DKX47]

I also like Readthedocs. Concerning language support: looking at the current docs non-english entries are so rare that i would question if that is really a needed feature. Just having the "welcome page" in your language but other entries in English is probably no real benefit for non-english readers

[ovpc]

Agree with languages part, there is hardly any activity there, nor has there been, so not expecting any, everyone seems fine with English. I did not like Readthedocs tho, there was no easy way to manage or restructure pages, it take its content straight from Github wiki pages. So not very easy to contribute without good knowledge of markdown. I am not going to spend much time on it anyway, but anyone who would like to take the job on is most welcome too ;-)

[nachoparker]

closing due to inactivity, reopen if you feel this is a mistake

[michuvon]

@nachoparker could you reopen this issue again? I will not be able to act immediately, but still like to start the discussion again.

---

I have the impression that as the documentation grows, it becomes increasingly difficult for users to get a good overview. Therefore, I like to get the discussion going again and see what we can do.

I agree with @theCalcaholic to keep the current setup with WP. But wonder if we could change the theme to something that looks more like the examples @Daniel-Krebs has posted. So, something with a sidebar for better navigation.

Additionally, we should reorganize the categories to be device/platform specific. That way, e.g. docker users find all docker relevant docs in one place. Documentation that applies to all platforms would get a separate section, e.g. Backup & Restore, Hardening, etc.

What do you think?

Who knows WordPress? Honestly, I would have to study quite a bit to change the layout/theme. But I could help get things sorted, and help categorize.

[michuvon]

@ovpc what theme is currently in use on docs.nextcloudpi.com?

---

Here is a list of some (if I'm not mistaken) free documentation themes: https://documentor.in/17266/best-wordpress-themes-create-online-documentation-wordpress/

[ovpc]

current theme from http://buddydev.com/ At the time was selected because only one supporting de translations plugin WP MultiLang

[michuvon]

thanks, @ovpc

So the first question we have to ask ourselves is, do we want and need multilanguage support?

Personally, I think it would be great, but I also see that there aren't really any contributors for other languages besides English.

[ovpc]

MultiLang was main, but not only reason to move to WP. Restructuring, editing and organizing existing pages was beyond my skills in Github docs. True: few pages have translations, and contributions have been far from overwhelming in numbers \o/ so I agree, it is valid question. If we decide to disable the MultiLang plugin, the website will look very messy tho, I think. It also will be time consuming to reorganize. It would not be fair to contributors, to simply remove translated pages, imho. Maybe they could be stored them in a sub-folder/page way, for them to still show in search results.

[michuvon]

I see. I would under no circumstances abandon WP. I think it's a great basis for NCP docs.

So I suggest we are looking around once more if there are other (free) themes with WP-MultiLang compatability. If not we should study more about the current theme BuddyDocs so that we can make the most out of it.

How can we find compatible themes? Is there a platform for easy discovery?

But honestly, I feel BuddyDocs can easely compete in uglyness with my profile picture.

[ovpc]

Easy discovery? Yeah that would be great, don't know of any. To find BuddyDocs I set up a WP on a test server, import content, install themes, enabled WPlang, trial and error. But then a lot has changed since, so we could give it another shot, if there is enough support and willingness to invest time.

Not entirely sure anymore about WP for documentation, maybe it be better served by docuWiki

[michuvon]

I spun up a WP instance on a LXC to try some themes and plugins. I have to admit, its a pain to use WP. It becomes very complicated. So I'm not sure any more if we should really attempt to change the Theme. We rather invest the time in cleaning up and organising BuddyDocs better, if we stay with WP.

docuWiki looks simple, not very modern but still more intuitive than BuddyDocs. I'm just not sure if we have the time and people to migrate all docs from one platform to another. It might be a process of several Months. And what about Languages, would it be less complicated?

Simply cleaning up the current WP setup would be much less work. I took the freedom and played around a bit with the current WP already and added some sub categories in Getting Started.

But I have a more radical restructuring in mind than just adding a few sub categories.

Also, I saw a plugin that let's one rearrange posts, so we can keep the important ones on top. Currently they move down with every new post - in that sense, our docs are more like a blog.

--

It boils down to this:

• Are we willing to invest many HOURS in migrating to a new platform (who will do the hosting)?
• Or do we only invest a few hours to clean up our WP instance?

What's your opinion? My time is limited, but I'm able to invest a 1-3 hours per week.

[victor-rays]

For my part I agree with clean it up and try some themes or plugins is the way to go, I think it could be too much work to move to another platform now when it's possible to work with what we have and explore some options there :)

[sunjam]

Migration itself is just 52 articles so it is absolutely do-able if we want to. There is also nothing stopping us from setting up a secondary service to quietly make the migration over time.

My thought is: I do not know a single service using wp for docs besides us. Not saying that is bad, just being clear. Personally, I've found wordpress to be excellent unless you only need static content (this would be us). So, we can stick with it or migrate... the main benefit of mkdocs or similar is a cleaner interface and using markdown for simplified formatting that looks great, either hosted on the site or from github.

Another option we do have is to just use the forum. I can create a dedicated category for NextcloudPi documentation and give everyone in a group, such as "NextcloudPi Documentation", write access. I bet I could personally port over our entire documentation in about 1 - 2 hours, biggest hurdle being the formatting translation.

Frankly, I greatly prefer the forum approach. It is easy to write up documentation in markdown at almost the speed of thought and tons of people see it. Code formatting looks perfect and everything works great. All respect to the docs team, this would be both easy and very much connected to the nextcloud project.

Anyway, food for thought!

[ovpc]

Forum approach sounds very good to me. We can leave the translated pages until later, they can remain available there, until a translator decides to recreate it/them on the forum. In fact the site can stay up as long as we want, indefinitely, afaik it doesn't cost extra as it's hosted on Nacho's account next to ownyourbits. Although it doesn't take that much time, due to lack of activity, mostly. It would still be a load of my back, managing the site and users. I'm working towards retirement end 2022. So would be cool to know the continuation of NCP's documentation in good and able hands ;-) Most of my time spend on NCP is on the forum and Github anyway, these days. Not thinking of retiring from that yet \o/. Note: Afaik the config-ref should remain a single tagged page, as the code links to it directly in ncp-web. edit; I thought wrong, ncp-web info points to https://github.com/nextcloud/nextcloudpi/wiki ?

[victor-rays]

Using the forums is also acceptable for me 😊

[michuvon]

Although I think a dedicated page would be the more clean approach, especially for navigation, I also see the benefits and ease of using the forum.

[ovpc]

We have started testing migrating docs to forum https://help.nextcloud.com/g/NCP_Wiki_Team/ Think we can close here for now. @nachoparker We can reopen if needed, but all work and discussions are taking place on forum presently. Thank you to all for contributing.