PLIP process regarding documentation

Development
1

On the PLIP docs they link to how to write docs.

While working on

I've been adding README entries on each and every package that I modified, as well as some general updates on the documentation (done by @MrTango) but I thought it was not enough.

It would be nicer that given each major plone release (i.e. 4.3, 5.0, 5.1, 5.2 ...) a set of chapters describing its newer functionality (PLIPs so to say): http://docs.plone.org/release/5.0/index.html and then a chapter for each PLIP: http://docs.plone.org/release/5.0/plips/xxx.html

Or is there another place (plone.org/.com) where these sort of high level overview of each plone release should be maintained?

One then could also use this high level overview to see the progress of new features and high-level changes made in plone from release to release...

Ideas, suggestions?

1 Like
2

Yeah, I wish upgrade documentation in the main documentation was a necessary requirement for accepting a PLIP.
Writing the upgrade guide for Plone 5 should not have happened after release.

3

+1000 !

I want this since a long time, documentation should be included into a PLIP, or now in drastic words [maybe over the top] no docs for your PLIP = no merge.

I know that sounds hash and it always depends of course on different things but basically it should come down to that.

We 'just' spotted again some features in Plone, which we have, but which are not documented at all, and besides really really experienced developers/long time users, people does not know about.

This is not a perfect situation, also not in terms of professionalism or marketing ....

I am telling this things not at least since 3 years, nice that finally some people see it too :slight_smile:

1 Like
4

At the moment its no fun to document things which then lay around in Pull Requests, because current docs are targeting the wrong release..

In order to document features for the next release we should then also have always a branch for the next release of Plone of the documentation repository - analogue to the coredev buildout branches.

I'am also curious how to spot where a feature is documented. At the moment grep and a good feeling for possible keywords is the best way to find the places (or the search of the generated docs, which results in the same need for a good keyword feeling).

5

@jensens that is only partly true, and I am sorry but I disagree here :slight_smile:

This is at least partly a question of workflow, nothing is stopping us to have a pre-release version, but still this only one point, what is stopping you currently to write documentation in the repository/branch of your code/plip ? having docs and releasing them are two different things, still if you want that we can set this up.

For example I have docs on stuff where I work on which is not already released, but when I release I do have already the docs.

Using that 'we have not dev-docs' build as an excuse for not writing docs is certainly an interesting approach but well ... :slight_smile:

BTW, I gave various talks about exactly this topic and how to solve that on at least 2 Plone conferences and on other events :slight_smile:

6

Ok, example: Given I make a change in - say - plone.scale targeting Plone 5.1 and there is already documentation in the documentation repository. The change is just a smaller enhancement or bugfix with documentatio needs and got merged w/o PLIP. But it is not planned to backport/go into 5.0. Now current docs are targeting 5.0, there is no branch on documentation repo for 5.1. Now my changes are implying a change/addition to the already existing documentation. Shall I copy this over to plone.scale, update, wait until we have a 5.1 release and copy back? I do not think that makes sense nor is it efficient. Also it is error prone, possibility to forget to "merge/copy' back is high - also conflicts are programmed. Better would be I could just change the documentation on a 5.1 branch and done. Easy, natural, no hassle.

So: If you want me to write docs, I just want to do it as easy as I write code: Give me always a branch on the documentation repository targeting the current head development and done. Same process, a no-brainer, easy to understand.

7

Hm I do not get it, or I do not see the problem here, that is why we are improving papyrus, ok it does takes time because not many people working on that ...

I will try to explain again:
The whole idea is to move to a more modern approach, which we already started a year ago, that is why you helped to start fixing papyrus, remember ?

This is WIP and we still have to fix that more, but this the way we go and not only we, lost of other Projects from Google/Mozilla?Facebook and some others are going the same direction already.

We are in the process of moving away form one huge big docs repo, instead we are already started to fetch /docs from the repos, that is why I am telling ppl to write docs, according to our guidelines in /docs of the repo in your example that would be plone.scale/docs.

This is of course also not perfect, but has lots of advantages compared to one huge docs file/repo. One main reason is to be more flexible with versions.

So you work on a branch of plone.scale for Plone5.1 right ? This plip/fix is only for Plone 5.1 and not for lets say Plone 5.0.4.
You work on the branch of plone.scale for Plone 5.1 or you will merge it later into it right ?

Is that right to here ?

So when we fire up papyrus, which will be done by CI in the future, papyrus will build versions for Plone 5.0.4 and Plone 5.1 and since you change/plip/fix is hopefully merged into the plone.scale branch/repo for Plone 5.1 this change will be fetched by papyrus and build into the docs for Plone 5.1.

This change will not end up in docs for Plone 5.0.4

If you/we really prefer to have always a 'dev' build of the docs under docs.plone.org/dev [just an example name] we could do that, we even[should] add a huge banner with these are the docs of the dev version [also just an example].

Would that be helpful ?

We have also tools like mr.docs and currently under heavy wip, a new app called wtd-stack, with these you can build and check the docs locally or with ci in seconds or minutes, depends what you are testing/building

That is easy, because you can write docs in the same repo/branch where you write code, you do not have to bother with any other repo, one place where you do it all.
A no-brainer and easy doable.

8

I really appreciate to have things like dexterity docs merged together in papyrus. This works fine. But thats not the point. While for plone.app.dexterity this works well: there are other cases:

I'am not sure if we want - or even can - split up all the docs that way. In fact lots of the docs are combined together, spanning several packages: plone.scale, plone.app.imaging, plone.namedfile, parts of the controlpanel in CMFPlone at http://docs.plone.org/develop/plone/images/content.html. For a reader of the documentation this is essential to get the picture.

For changes in this parts of the documentation a coredev-synchronous branch of documentation would help a lot.

9

Well this is really the long term vision, and yeah we are talking not of all the docs are getting spliced but where is would make sense and stuff easier.
This will also make it easier to maintain the docs which are we not splitting.

The other thing is, at some point we have to rewrite parts of our docs anyway, this is/will be a long going process which will takes time, but this will also change a lot.

This has, besides technical stuff to do with tone of voice, wording and so on.

Like I said this will take time, but it will be happen, for example we are already started on that with the installation docs, we are doing that in a couple of steps.

One other important aspect is, that is makes testing of the docs way easier and faster, that means better quality and more releases !

The way of documentation and how people see it is changing, you can also see that with/on other projects.

I will check what we can do about a coredev-sync build, soon.
But there is one point to tackle first, and that is versioning, meaning if we do a docs build for every version that will not work for normal user, because they are getting confused, like:
a docs build for: 5.0.1, 5.0.2, 5.0.4

-> this may work for devs but not for normal people

on the other hand:

docs build : 5.0, 5.1, ... will work and that is what we are doing now

for changes in minor versions, we use ..versionadded:: [ http://www.sphinx-doc.org/en/stable/markup/para.html ]

10

its completly ok to have one target per minor versions, if this includes the upcoming/next planned minor version so in parallel of working at the code also the documentation can be prepared. I dont see any value in separating documentation for bugfix versions.

11

Also, I am seeing there is now a 5.1 branch for docs :slight_smile: