Oh, there is a sprint? I was not aware of it. Now I found the link at the Tagungsseite. I try to attend. However, I can go through some parts of the docs if there is a team doing docs at the sprint. I would take the more technical ones. If there is no doc team, I am happy to sprint on other topics, like Plone 5.2/ Python 3.
@tkimnguyen I think another thing we can do for new devs, in the case that they are Web App developers, is also provide them with plone.restapi and its documentation, and also give idea about the projects that already have been implemented using it.
Thas are good pointers, but the problem is the structure. The training is to long to not scare people and the docs are confusing even for me some times and I know that shit for years. But I thing we have a plan, we just need to work on that. @svx work plays an important role in that. We need updated docs soon. And a group who makes the docs more accessible. New target audiences (enother type of developer) as @ajayns pointed out are also a good way to go to reach more people.
There went already a lot of preparation work into the training to do that.
I know that is not known by everyone
We are already able to build and deploy only certain trainings, for example.
We started with that exactly of this reason. The work is not done 100% and we are still looking for a 'design person' to finish that.
So if you are good with CSS, HTML, Jinja, etc, talk with us
Is there a way you can add a chapter or reorganize what's there in both Get Started with Plone and in the existing docs rather than start all over? Evolutionary I think will have a greater chance of success.
@svx i got this, we have to work on it
If you make a doc sprint, I'll try to join it.
I'll work on that topic docs/bobtemplates/plonecli during the sprint in Berlin too.
More accessible means the already stated consitent structure. So that inside on epath of the docs, lets say for the developer audience. We will have every thing what a developer needs. It could b ethat same parts are also in some of the other paths (Audiences) in the docs for example the templating will also be part of the "Integrator" area. We can symlink/include them somehow I'm sure. This way, I decide what I'm looking for and will find all I need in that area. Sometimes it's event to much docs in the menu. When I startet, we had the Zope2 Book and it was a really good source for informations. Event today I go there to look up details of templating if I need it, because I don't find them in our docs ;). https://zope.readthedocs.io/en/latest/zope2book/
@tkimnguyen get-startet is just another overview, it does not solve the problem of spreaded informations in the docs.
The new topic "app/api development" can be included there of course. But first we need to have in the docs. I thing this should be a new audience group on the top level.
I just watch the video of zour talk, but there is no real reason why it is not cool to use includes.
Except to not include stuf on places where there not belong.
I get the point, that it's better to have every info in the right speaking for every audience.
But, life it not perfect and sometimes it's better to find the docs for a topic than not finding anything at all.
And if we look at developer docs and docs for integrator.
They are overlapping or are even partly the same for some stuff.
For this we need to have some content in more than one place.
Because different people are entering the docs in different ways or are in compete diffenrent audience groups.
Don't get me wrong, I want as much good documentation for every target audience as possible.
But most of all, I want to fill the gaps of not finding the right docs.
If you have better ideas to fix the problem of not finding somthingbecause it's not where you thing it should be, I'm listening ;).
Ok @svx thank you for clearing this up. Now we all know what is bad, but we still have no solution to the problem.
What about, instead of including things, using simple pages which point some links to the other area, if there is not more info?
I mean the concret problem i found was with templates and views.
I would expect all the needed docs in the developper area in this case.
Even though some of the infos are also interesting for Integrators.
But for Integrators, there could be an intro page with some infos, if needed with links to developer docs, which explain more technical stuff. Sure the speaking in the developer area might be a bit different, but that should be fine, if someone want to dive deeper into a topic. There is no strict line between a being a developer or an integrator. Of couse the best would be to have a special chapter just written for Integrators, in the right language with the right amount of information they need. I'm not holding anyone back, to write more Integrator or user docs. But my focus for now is, to fix the developer story of Plone first. And the most docs we have in these two areas are developer docs, in information and tone. So I would restructure it a bit, to have the developer part complete and fill the gaps in the Integrator part with index pages with a summary, which describes what can be done and points to the dev docs if needed.
Beside that, I thing we should build a Developer Crash Course, like the training but more condenced to a backend developer audience. This way it is easier to get people on board with backend developing. I'm thinking of material which takes not more than 1-2 days to go thru. This training should also have pointers into the dev docs, for details information about the different topics. I would like to have a discussion about, what people thing a backend developer should learn first. But I'll start another topic for that.
I also completely agree with you on the current situation, the whole integrator developer thing is IMHO not really right anymore!
Maybe we should think about getting rid of this kind of distinction, and solve it in a different way.
I mean a "integrator" is basically are doing "easier dev stuff" right ?
So how about the idea merge the docs, start with 'easy' stuff (providing quick links to advance, that people can skip) and moving in a logical way to the "hard-core" dev stuff ?
There are some things to figure out first, like the whole TTW story.
I am saying this, because before ppl now start moving stuff we should have a clear picture of the current situation and all its possible impacts and a clear picture and vision about the goal.
Plus we have to keep in mind what is planned for the next Plone versions, since we do not want start all over again in a couple of months.
So yeah, I totally agree, but please a plan first !
if you go to some random page on the tinymce docsite, for example
you will notice in the upper right of the big blue box a button 'contribute to this page', that is leading directly to the github page, when trying to edit when having no edit right it creates automatically a new fork. That could be interesting for all the small corrections that casual readers would find appropriate. It still requires a github login though.
Provide a way for developers to build the docs locally
Improve the search results UI
Search content is not a problem for me. The UI is a serious and horrible technical problem. It makes me frustrated, and I instead use duckduckgo.com for better results and UI.
When you type in a search term, I see only 5 results with no useful context. When I try to open a result in a separate window, some stupid JavaScript seizes control of Command-Click, opens the link in the same browser tab, and I lose the list of search results. If the page is not what I seek, then I have to type in the same search term and try the next item. I would much prefer the simple and usable standard Sphinx search results, which provide necessary information and usability in comparison to this Algolia rubbish.