search

agentejo / cockpit

Add content management functionality to any site - plug & play / headless / api-first CMS
http://getcockpit.com
MIT License
5.4k stars 523 forks source link

contributing to the docs - some clarification and ideas #793

Open raffaelj opened 6 years ago

raffaelj commented 6 years ago

Short version: Let's update the docs.

I collected a lot of information and wrote some thoughts about missing docs and restructuring them. You can skip the background part.

Content:

tldr:

@aheinze invited me to contribute to the docs. I'm not that experienced and my English is not the best, but I'm willing to learn. So...

some background

I'm new to headless CMSs and all about APIs, but fiddling around with Cockpit in the last weeks made me love the concept. I came from cmsstash (German article) and found only a few self-hosted + free and open source headless CMS. Actually, I searched for a replacement of jekyll with prose.io as backend. I decided to test Cockpit, because

When @aheinze removed gravatar, I was sure, this CMS could fit my view of data privacy. I fiddled around some more, I read the issues and a lot of (clean) code.

I see the potential to use it for some or maybe all of my future projects and that I never have to touch bloated WordPress plugins again.

Now I want to contribute to the docs, share my knowledge and discuss some structure.

confusion about repos

cockpit-docs

If I understand it right, than https://github.com/COCOPi/cockpit-docs contains outdated information and tutorials and was for the legacy branch.

https://github.com/agentejo/cockpit-docs is the actual version for next and contains everything on https://getcockpit.com/documentation

cockpit-i18n

empty repo: https://github.com/agentejo/cockpit-i18n old repo: https://github.com/COCOPi/cockpit-i18n

another source for i18n files: https://github.com/agentejo/cockpit/issues/410#issuecomment-215515242 https://github.com/aheinze/cockpit/files/241154/cockpit-i18n-master.zip

information around cockpit

It is a bit confusing, to find the right place to find informations or to ask for help.

Missing docs

more intuitive design

Some thoughts about a structure, I could imagine...

The current layout is:

Getting started
  Introduction
  Requirements
  Installation
Modules
  Collections
  Regions
  Forms
Reference
  Configuration
  Fieldtypes
  Docker
API
  API Token
  Cockpit
  Collections
  Regions
  Webhooks

How it could be:

Getting started
  Introduction
  Requirements
  Installation --> with optional use of defines.php
    Docker
Use Cockpit
  First start --> Dashboard, Navigation, create first collection, upload asset, change username and password...
  Settings
    System Settings --> Basics with link to Reference/Configuration
    Accounts
    API Access
    Webhooks
    System Info
  Modules
    Collections
    Regions
    Singletons
    Forms
  Accounts
  Assets
  Finder
ACL, Users and Groups
  config.yaml
  API Tokens
  Accounts
  Custom Module Permissions
  Groups-Addon
Reference
  API endpoints --> complete list
  Fieldtypes --> complete list
  Configuration
    Cockpit Settings --> complete list
    Custom Settings --> i18n etc.
  Events for Webhooks --> complete list
REST API Access
  API Token
  Cockpit (Users, Assets, Images)
  Collections
  Regions
  Singletons
  Forms
Access via PHP (Bootstrapping)
  ... --> Lime, cockpit(), find(), findOne() etc.
Extending Cockpit
  Addons
  Custom API endpoints
  ...
FAQ
Examples and Tutorials
  Simple Blog
  Granular User and Group Permissions
  ...

This is it for now. Maybe I have some more ideas in the next days.

@aheinze What do you think about it? With a structure/to-do-list like this, it would be easier for me and others to contribute missing parts of the documentation.

edit:

raffaelj commented 6 years ago

To contribute to cockpit-docs, I have to understand that repo too. It seems to be a subfolder named "documentation" of the content directory of a private copilot instance.

I did some tests with copilot and it is possible to add new pages as .md-files without adding uid, created, modified, type, teaser etc. to the frontmatter. uid and modified are added from Copilot after editing the page from inside. It's also possible to add pages directly as /new-page.md instead of /new-page/index.md.

Adding a README.md without a title in the frontmatter into the content directory leads to an unclickable page with no title in the Copilot backend.

The pages have types documentation/group and documentation/pages, but the site directory is missing. I have no idea of the configuration of these types.

Questions:

Could you decouple the docs from your homepage or make the whole repo public? -->Than we could clone it, edit it via Copilot or via text editor, push the changes and make a pull request.

If not: If I create new pages - Is it neccessary to write the types by hand into the frontmatter or is the layout created dynamically by the folder structure?

monkeyphysics commented 6 years ago

I tried out Cockpit this week. The official documentation is indeed lacking, and through Google came here. @raffaelj's efforts are great, and he deserves some support for trying to help and build the community. +1

piotr-cz commented 6 years ago

Good job with collecting all this info. I suggest to start with small steps, one docs section/ file at a time. In every pull request describe in short what you've added.

raffaelj commented 6 years ago

Thanks. The collection grew first as a personal list to find infos again.

And yes, I think small steps are fine. Cockpit has 3000+ stars without a perfect documentation and nobody will die, if it takes a while to update it.

jankal commented 5 years ago

@raffaelj We have started rolling new docs on our own due to @aheinze seeming to have not enough time for it. You can contribute here and view it here. I think your suggestions are pretty solid and do represent a lot of the info needed. I think, we will also adopt some points from your list. As of now, our docs are still in development and far from complete. We chose to work with the awesome VuePress generator to support rapid docs writing. What do you think?

aheinze commented 5 years ago

@jankal Great initiative. I'm looking forward to see the final result (and hopefully seeing it submitted back to the official docs 😉 )

raffaelj commented 5 years ago

@jankal Nice work. Where do you want to talk about it? In the issues of your unofficial docs, on discourse, here...? I would like to help, but I don't have much time in the next weeks.

I did some more research in the past. Maybe that helps:

jankal commented 5 years ago

@aheinze it's very encouraging to see that you kind of support this. I would have already made PRs and contributed to your cockpit-docs repository but I really didn't know, how to set up a development environment for it. So I opted to create something new. I think, this will bring new life and openness to this project because as of now it seemd to be somewhat closed because it's hard for other developers to first understand Lime (meaning something, nobody has seen before) and other 'solo-projects' of yours.

This is the reason, why I opted for VuePress... it uses commonly used and known technologies and people can contribute to it much easier. As of now I do not intend to submit the documentation back into your cockpit-docs repo just because the developer experience is bad and I really not a fan of the design on getcockpit.com. I rather intend to replace the old docs section.

@raffaelj Thank you very much for these resources. Many things here in this issue are of good use for me even if I still have to scout the code. Let's try to work on it within issues/prs on the new repo, so the main project doesn't get even more 'unrelated' information.

jankal commented 5 years ago

@raffaelj When you do support my efforts of creating entirely new docs, I would give you push access to our repo so you don't need to submit PRs all the time.

raffaelj commented 5 years ago

@jankal I support your efforts, but I never used Vue before - and as I said: I don't have much time right now.

I don't need push access. I'm always confused with merge conflicts ;-) I like (and obviously need) the workflow with one PR per change.

jankal commented 5 years ago

@raffaelj I added your samle debugging guide to our current dev version. I clearly stated that it was written by you. See here.