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?
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.
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.
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:
Changelog
Technical environment
Knowledge
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.
Thanks so much for the very comprehensive answer @raffaelj! Sorry for the late reply, I haven’t been in office for the last two weeks.
I will try to answer your points and with focusing on what just users (like me) without any insights into the code or the used frameworks can contribute.
Changelog
Yes, I absolutely agree on this. Upgrading has been quite nerve wracking for us so far Without being involved in the development this seems to be something that should really been taken care of by the core team imho.
Technical environment
I think from a practical perspective starting off from zeraton’s inoffical docs is probably the option with the highest chance in actually improving the current situation. Both because it already has a lot of content and VuePress seems to be a good choice from a technical point of view.
Since the zeraton docs have not seen any update in the last 2 years, we should probably work on an “official” fork though, right?
Knowledge
This seems to be by far the biggest issue to me. For developers like me, without reading the code, I suppose the biggest contribution could be made in the regard of adding an end-user documentation. As far as I have seen so far, there is actually no documentation for end-users whatsoever. This is definitely something I will try to contribute too.
What I could also try to do is, trying to accumulate the knowledge from here and transfer it into the docs.
Crowdfunding
I think that is a really sound idea. I don’t really have a feeling about the amount of users of cockpit. So I am afraid it will be rather unrealistic to gather enough money, to make your times worth.
Conclusion
All in all I feel that cockpit really is an outstanding project, perfectly suiting both developers and end users. My honest concern is though, that it looses a lot of potential users and with this also a bigger and more active community by being so poorly documented. So I really feel this is an absolutely crucial issue.
I will try and see what I can contribute in the next weeks.
Personally, I’d appreciate some documentation on the built in PHP SDK. There’s little to no documentation online about this but it’s extremely handy.
I am starting to write detailed documentation. Because not existing detailed doc is an important issue of the cockpit. It seems this forum help me a lot in this survey
Without being involved in the development this seems to be something that should really been taken care of by the core team imho.
