Broken links in docs.plone.org

Thank you all for jumping in on this. Kudos to @ajayns for wanting to help!

https://plone.org/get-started is one place we try to get new people started, plus https://docs.plone.org/develop/index.html

What other ways could we get new developers on board more easily? Perhaps we could start a new forum thread for ideas.

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.

1 Like

@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.

1 Like

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 :slight_smile:

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 :slight_smile:

@ajayns Plone RestAPI is not yet in the docs, because of various reasons:

  • untill some weeks ago there was no stable (as in official 1.0) release
  • the way how the docs of the API are done are different than the other docs

Things have changed and we have to think now how we want to do that.

@MrTango would you mind to explain a bit more what you mean with "more accessible" ?

I mean, I 150% agree with you on that ! :slight_smile:

I also pointed already on various locations ( also here out) that this is known and we're busy with that :slight_smile:

Thing is we need more people to help :slight_smile:

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 :wink:
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 am happy that you added somehow :slight_smile:

I do not want to repeat myself, but "includes are not" cool !

I covered and explained the reasons in my talk in BCN :slight_smile:

Awesome !!! :heavy_check_mark::+1::clap::grinning:

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 ;).

@svx is a documentation super hero!!! :slight_smile:

2 Likes

I am honestly and with all respect disagreeing :slight_smile:

There are lots of reasons:

  • tone
  • ripping things out of context
  • assuming knowledge of people and what they did/read
  • wording
  • style, length, readability and visual appearance
  • missing content
  • broken links
  • breaking releases

I could continue here with a lot of more reasons :slight_smile:

Thing is, people (developer, no offense ! :slight_smile: ) thing quite often, 'just' use a include and we' re done ....

Most of the time a link to the document or part of the document would be way better. Because you do not take stuff out of context, etc, etc :slight_smile:

I took almost 3 full work days to fix that on all the training docs and we' re still not 100% done !

People (user, reader) got confused there, docs were broken, etc because of reasons mentioned above.

I see the same by lots of projects who including their README as index.html in their Sphinx based docs.

This is wrong !

There are fundamental differences between a README and a index/intro/teaser/about of your project. :slight_smile:

:slight_smile:

2 Likes

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.

Sounds good !

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 ! :slight_smile:

1 Like

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.

...and a Plone Contributor Agreement.

https://www.gnu.org/prep/maintain/maintain.html#Legally-Significant

  • Automate docs builds
  • 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.

1 Like