Thoughts about moving core packages docs into main docs

,
1

It's hard to use the docs of the core packages in the central docs. We need to be flexible here where we can put informations and if we have to include a complete part from external package, we can not adjust them to fit the structure. I suggest that we move all docs of all core packages into the central docs if there of interest for it.
We can still have readme's and some docs inside the packages, but things like the dexterity developer manuel, the plone.api, plone.restapi and many others should be in the central repository and rendert centrally.
This way we have a chance to reorganize the docs, as we need it, to make the whole documentation more fitting together and easier to use.

@svx @jensens @pbauer @mauritsvanrees @tisto how do think about this?

2

The docs are an essential part of plone.restapi. We use a documentation first approach and we would have to spread our pull request across multiple packages if we would follow your suggestion.

In the long run, I'd suggest moving to a mono-repo approach for Plone core. In the meantime, I am strongly opposed to moving docs to one central place (at least for packages that are clearly separated like plone.api and plone.restapi).

1 Like
3

I am still on vacation because of this I keep it short for now :slight_smile:

We had that before, we even tried that again and again for a couple of times and this is not working.

This is aslo logical because you force developer to checkout just another repo to update docs.

This adds more friction and will not work.

Also I do not understand your point, your proposal will not make it easier in terms of structure, QA, etc....

Why you think it will ? :slight_smile:

Further I do not understand why you can't write docs in the docs dir of a repo that follow and fit our style-guide.

We can include the docs on every place we want under every name we want, etc.

The problem we do have atm is that the docs in some of the repos we fetch are bad but this will not change if you move them to the core docs.
Another problem is that for some of the repos we fetch the docs from it is not really clear who to ask, etc.

This should change.

And just another point, for some docs like the plone.api the way to build is different because of the way how the docs here are done, this is not easily integrated into the core docs.

Last but not least, as I said I will write the whole blueprint about the docs and the future down as soon as I am back from vacation.

There are for example valid and important reasons why we should be able to build and push just the plone.api or dexterity docs without building the whole core docs.

Think for example 'canary' deploys and way more stuff like testing.

Speaking about the plone.restapi docs there are a 'special' case again, we can't just include them :slight_smile:

Like I said more on that as soon as I am back (in 6 days more or less)

2 Likes
4

@svx enjoy your vacation :wink:

Just some comments so far. We can make exceptions if it make sense.
And there might be some good arguments.
We can discuss this, thats why I started this topic here.
The main reason why i would like to merge at least some of the docs, is that it's nearly impossible to write down a good documentation if the content stays in different repos, is managed by different people and so on.
I see the advantaches of separated repos with the docs, don't get me wrong.
But my wich is to have a good documentation, which focuses on the audience and has a consistent structure and has a clear thread running throug. This is not easy to archive, if you combine things which are belong to different packages and documentations. If the docs repo is easy to rebuild, I don't see why we shouldn't be able to manage the docs centrally. At least for topics like dexterity, fields, widgets, templates.

We have so many packages, that it is impossible for new peaple to find there way thru it, so after a while they will just quit. So we need to rewrite the central docs to have a complete story there. I see only two ways of doing this. Either by moving some existing docs like the DX docs into the central docs and integrating them in the rest of the docs or by writing meaning full docs inside the central docs again, which would lead into having information for the same topic in different places with different versions and so on.

The way we include the external docs now, is better them having them not in the docs.
But it does not feels like one documentation which leads me to what I want as a developer.
It feels more like a collection of a lot of docs, which are fitting well together.

If you have ideas how to improve this an a better way, I'm happy to hear.
Regarding the api packages, they could stay separate, i don't see a big problem here, as they can stay for them self. But for a lot of other packages, thats not the case.
For these packages I would say, let's keep the docs for developing the packages it self insode the repo and move everything which is useful for the central docs there. Tha will allow us, to put every peace of infomation where we things it belongs, inside th docs. Regardless of to which package the peace belongs to.

5

To give an bad example, look what we have for vocabularies:

6

Yes, I know.

I also understand your motivation ! :slight_smile:

The situation we have is confusing and far from perfect, there are various reasons why we have this 'mess'.

One of them is that we did things too fast without enough thinking and knowledge last time we re-structured, cause we wanted to 'make things better fast'.

I want to avoid making this mistake again, I also do not think that your suggestion will solve that, even more I (no offense) think you suggestion is the wrong way to approach the problem :).

Like I said before, we should take a step back and first think and look what we want to achieve.

Taking your example from above we should decide which of these are needed, could merged, re-written, etc, etc.
Also we need to take care that this matched with training.plone.org,

This is an important point currently we have also the mix of docs and training with sometimes different info on the same topic !

If we re-structure we should do it right.

Back to your example from above, true we do not need always external docs, but if and how we merge/move should be decided on each one carefully.

We tend to forget the 'normal' user, for example I personally would change the whole docs structure.
Make it easier for the user, so move for example theming do docs.plone.org/theming and done.

Just forget the nested dir structure, flat is easier for user.

1 Like