How can the community support developing a better documentation?

Hello,

we adopted cockpit for our project in March and especially the last 2 months I have been working heavily with it. I really think it is a great tool and it covers 99.9% of what we are looking for. Thanks a lot for that!

So far my only frustration has been, that the documentation is minimal. Support here works well, but I think 80% of the questions which I asked here in the last 6 months, could have easily been covered by a better documentation.

Since we take great use from this tool I would really like to offer my support on helping out with the documentation. Especially since I was lucky enough (at least that’s how I consider myself) to never have to code PHP in my life, so I cannot be a lot of help when it comes to actual coding.

Problem is, I don’t know the code and all the hidden, undocumented functionality this tool provides. So how could we, the community help in improving the documentation?

Best! Tom

1 Like

Same here, I was frustrated because I switched most of my projects from Wordpress to Cockpit. I also wanted to contribute the docs but my English isn’t good enough.

If you want to contribute the documentation, you can send PR to this docs repo. But there are many PR requests that hasn’t been approved yet, probably agentejo is busy with his other tasks.

FYI, this unofficial documentation by https://zeraton.de is a bit more detail than the original one.

Good question and thanks for offering your help. I learned cockpit by searching through the issues and reading the source code. After understanding the Lime micro framework, suddenly the whole structure made sense. Now I know where to look in the source if I forgot a function name - and I created the cockpit-scripts repository for notes and custom snippets.

I think, that’s not a big problem. It takes the most time to collect resources, to write example codes and to structure content. If this part is done, it’s easy to rewrite it and to fix some grammatical issues.


And I have a déjà vu… Have a look at this thread from two and a half years ago. I started to collect a lot of resources and thought about a better structure for the docs.

Personally, I would drop the whole docs section on getcockpit.com and either use the inofficial docs from zeraton or create a new docs repository with a common system like jekyll/gh-pages. The new docs could than be available at docs.getcockpit.com or to clarify, that it is a community work and not the official one, on a new domain like cockpitdocs.com.


So how do we fix the docs?

I see a few main problems:

  1. Changelog
  2. Technical environment
  3. Knowledge
  4. Time

Changelog

Cockpit really needs a CHANGELOG.md. Trying to keep on track with the latest changes after a few months is really hard if you don’t read the commits every now and than.

I think, this is a relative simple step to be done by community members.

Technical environment

It should be any kind of flat file cms with markdown for clarity and git based version control.

The official docs seem to be a subfolder named documentation of the content directory of a private copilot instance. It is based on markdown files, but with an uncommon frontmatter and it is impossible to build the whole page locally. So this one is out.

Since the unofficial docs already exist - with a lot of content - VuePress seems to be a good choice. I can build it locally with npm run dev or npm run build. Only a few custom blocks are used (e. g. ::: tip), so it should be easy to port the markdown files to a different system if needed. It looks like a good choice.

Otherwise, I’m already familiar with jekyll on a gh-pages branch. It doesn’t need an extra deployment step. After a simple push, Github renders the page automatically. And I could use the powerful kramdown instead of markdown.

And Hugo is incredible fast.

I vote for the existing VuePress, because it exists and it is portable.

Knowledge

There aren’t many people around, who read most of the source code of cockpit. Some features aren’t documented, because they are experimental. @artur has some plans for the future, that we aren’t aware of. So some code parts might not make sense, yet.

Also it depends on your focus. The admin ui is based on Lexy, riot.js, jQuery and UiKit v2. The core is based on Lime, some well-known libraries and some unknown libraries.

The whole concept of cockpit is to allow developers to change nearly everything with 4 interfaces:

  • php/module api
  • REST api
  • cli
  • admin ui

You can use it as a library or as a data storage for external applications. You have to care about security if you have a multi user setup with backend access. And everything changes, if you use addons.

That are a lot of possible edge cases and things to keep in mind. We need a documentation, that addresses

  • casual users, who use the defaults, are willing to click through the ui, but need one custom api endpoint
  • addon developers, who need to understand Lime, the controller structure and also Lexy, riot.js and UiKit
  • advanced users, who
    • develop with docker and/or composer,
    • run cronjobs to feed cockpit with fresh data via cli,
    • use webhooks to trigger Hugo builds etc.
  • end users/clients, who can’t login because of the missing FormData polyfill for Internet Explorer

So if you feel like an expert or an advanced user in any of these sections, you could click and scroll through the inofficial docs and add some missing parts.

Time

Obviously @artur doesn’t have the time to document all the great (new) features. @jankal spent a lot of time on the inofficial docs, I wrote multiple long explanations and guides here in the forum and a lot of other people contributed to the docs as well. I can’t mention all of them.

But I guess, it still takes a few weeks to write the whole missing docs with a tutorial section. Also, if Artur doesn’t slow down with adding more features, updating the docs will take some time in the future.

If you have some spare time, have a look at the missing parts in the inofficial docs and send a pull request.

Another idea

Theoretically, I have the time to write docs and also to spend more time in the support forum. But I can’t do it in my spare time. To be honest - my main target group works in the artistic section and you may have heard about some pandamic going on, that prevents artists from being able to spend money. In short: I search for a job right now. If I find one, I will have less time for cockpit support and for writing new addons or updates. If not, I have to spend more time on finding one and I still have to pay my rent.

I don’t want to beg for money, but I really like the idea of a crowdfunded part-time job, that involves solving interesting problems and sharing my knowledge. I didn’t think this through yet, but I wanted to mention that option.