A long time ago, the decision was made to base the docs and all examples on Ubuntu LTS, since the installer docs were already based on it, to give the docs more consistency and because it is hard to maintain X different OSs.
So lets take that out of there and find a hopefully proper solution, which fits the whole documentation, it make no sense to change it only in some tiny parts because this is will confuse user.
If you change that we need to find a solution through the whole docs to have it consistent.
Things to take care of for example are [there are more]:
Installation ?
Dependencies ?
examples, how you want to solve that like install paths or other stuff ?
tools, we mention tools which are easy to use and to install in Ubuntu and OSX but not in CentOS, how to solve that ?
...
...
If you choose one OS for the examples, why that one and not the other one ? Ubuntu vs CentOS ?
I am not even mention other OSs here
I believe it is a sane policy to assume a single distribution for examples in the docs.
Except for Administration tasks like the one mentioned in the PR. There the focus is not only on Plone, but the complete environment in which it runs. Not mentioning other distributions is not ok.
The suggest method to install Varnish is to use your OS package manager.
* You can install using packages (DEB) - consult your operating system instructions.
* For more up to date packages for Debian you could check: https://www.varnish-cache.org/installation/debian
I'd write:
The suggested method to install Varnish is to use your OS package manager. For more information see: https://www.varnish-cache.org/installation/
So well, difficult. I dont think consistency is the major question here. First it depends on the target audience.
A beginner would like to have instructions for her/his OS. This kind of human has not enough learned to transfer Ubuntu LTS instructions to CentOS.
OTOH In-depth topics are usually not dumb recipes for beginners: we expect people to switch their brains on and so a LTS-only instruction is here enough to explain the process so a professional can transfer this to her/his OS.
I'd love to see more than Ubuntu LTS specific instructions for beginners. Having one major RPM based system as well - like CentOS - is also a good idea. OSX maybe too. At least for the core installation process. But... its a lot of work and if all is in one document it does not increase readability.
For third party stuff I agree @thet to point people to the original docs, at least if there are any good. This also ensures to point to uptodate docs - hopefully
A solution for readability would probably to use tabs to switch between example parts inside the text for the different OS, maybe using a cookie to remember users choice. I already saw this for api-code-examples somewhere and liked it, but have no idea if there is a sphinx extension for such a feature.
A bit of docs history here, just to explain it maybe, exactly that was one of the reason why we settled once on 'based on Ubuntu'.
Yes that is not perfect but, seeing since a long time how much ppl are actually working constantly on the docs, I can really see the reason why we went for that.
What I am trying to say is that it is really a lot of work and to all the docs and with only 1.5 till 3 ppl it is just not possible.
That is also why I wanted to have this discussion I only hoped it started in a better way, but anyway now we have it at least.
I would advocate to be pragmatic. Yes, the guidelines should be clear, but perfection is the enemy of progress. So, I would propose as general guidelines:
where possible, write distribution-neutral
if we can point to other (stable) docs, do that. Less work! More up-to-date docs!
where explicit examples are uses, use Ubuntu LTS. If short, concise links for other OS's can be given, link to them (but do not include the specifics in the docs)
and then, indeed, be pragmatic. In the Varnish case mentioned above, I mentioned Debian, RHEL/CentOS and FreeBSD because https://www.varnish-cache.org/docs has guides for those.
On the other hand, I agree that for docs that tell you how to install helper tools for writing or reading docs, a description of Ubuntu is enough.
It's all about audience. For the install/deploy docs, those are sysadmins. There, we have a lot to gain from mentioning multiple OS's (hey, it works on my favorite setup), and less to loose (they are less likely to be confused)
for 'enduser' / 'testing' audience, go for the simplest option possible.
@polyester I am really sorry but I disagree at least partly.
This brought us exactly to where we are know, and I really want to avoid silly comment-exchanges and instead would like to focus more on improving docs.
So yes, we need clear guidelines but we also should try at least to follow them, otherwise we do not need them at all and they are just a farce.
Further on you are saying two different things, at least that is how I understand it. On the other hand you telling: It's all about audience. On the other hand: On the other hand, I agree that for docs that tell you how to install helper tools for writing or reading docs, a description of Ubuntu is enough.
This will be confusing for new user, maybe the new user is using CentOS or Fedora, and want to be use tools, like rettext, pandoc or whatever tool ?
Here I fully agree with @jensens he is completely right, for a new user it is hard to transform a Ubuntu example over to CentOS.
I guess I didn't express myself clear. For the helper tools to write/read docs, the audience is different. Personally, I think it would be most useful there to have Windows, OSX and Ubuntu mentioned, so my earlier comment of "ubuntu is enough" is not strictly valid.. Yes there may be a beginner on CentOS, but the changes she will be on Windows or OSX are much higher, and we have limited resources/people.
For sysadmins, I have the feeling that not mentioning at least CentOS/RHEL and where possible FreeBSD is hurtful in the "docs as marketing" aspect. (and yes, sysadmins are a target for marketing/mindshare). There is a sizeable sentiment of "don't just mention Ubuntu when you mean Linux" amongst sysadmins, for instance.
It does mean that there is tension between consistency across the whole docs and audience-focused in different sections; sometimes doing the one hurts the other.
I agree with polyester here.
Docs that are primary for getting Plone working in an existing environment benefits from targeting multiple environments,
Docs that are primary for understanding Plone itself distract the reader if there are explanations for many different OSes.
I don't want to read about nix specific instructions to get portlets customized, the explanation of how to behead the chickens at midnight is gross enough.
When reading about log analysis and extraction I'd be glad to read how to that in docker.
In my experience I would say that newbies (like me) use Ubuntu; anybody using CentOS or Fedora probably knows better how to do many more things and it wont be hard to translate installation instructions or other stuff; providing links to alternate documentation is fine.
On the other side, I'm against maintaining documentation for non related Plone stuff; I just took a look at the nginx and Varnish documentation, for example, and I don't think they are as useful as they should be.
IMO, it would be better to:
use always standard ports on examples
provide recipes to solve Plone specific problems
set only options that are mandatory for certain feature
Configuration examples provided for ngnix are plenty of options that are not really needed most of the time (like the ones for proxy caching which is indeed not rudimentary at all, but very powerful and easy to configure indeed).
Same happens with the Varnish configuration example: seems that we haven't understood how Varnish manages VCL and ended up including the whole standard configuration which is, most of the time, needless. Also, I've never seen Varnish caching error pages so that part seems to be useless.
Things to check forward:
how to limit nginx request processing rate to protect parts of your site like search forms
the purging configuration for Varnish 3 is incomplete
@polyester it was never about not mentioned, it is about to figure out a way which makes sense and logical for all aspects and parts of the docs.
And this should to be done in a way that fist all the kinds of different user, is logical and easy to understand.
@do3cc, I am sorry but your argument with docker logs, make no sense, in combination with the rest of your last statement, or I do not understand what you mean, according to your sttement my answer in the docs would be something like:
I like the idea of having general instructions be distribution neutral while having examples be oriented to the most recent LTS.
(By the most recent LTS, I don't strictly mean Ubuntu only. Ideally the examples will work on the latest LTS and the matching Debian. So, Trusty and Wheezy.)
For me, having the examples oriented to one distribution is not just about audience. It's also about maintenance. IMHO, our RPM-world documentation has suffered over the years from very uneven maintenance. For that to change, we'd need to get the sub-portion of our community that's RPM oriented much better organized towards documentation and installation.
My main point is that I do believe that distribution neutrality is not a rule that is applicable for all documentation.
I gave docker as an example because how to do proper logging depends on the application, plone in this case. So it makes either sense to say, mount your log directory as a volume or here is how to configure your plone to send logs to a specific volume mount, or here is how to send logs to syslog and here is how to configure it in such a way that it works even if you start the container without adding a link to a syslog container or whatever.
Docker does not know how to configure Plone, we do.
I understand the tension between wanting to get something "perfect" and just wanting to get something there. I don't know the best trade off if it's between "I can't find the docs to do X" versus "the docs to do X don't apply exactly to my situation" (or "the docs to do X aren't quite correct").
My bias is towards getting something there that is pretty good.
I think in general docs we should ideally stick to using the most popular OS as our cited example, versus what we would do in OS-specific docs such as for installers.
Weighing in from the semi-outside, Plone-inactive state (which may be helpful here): for a random selection of open source projects both large and small: should documentation about the project pertain to a "neutral" distribution of Linux? Or do you mean OS-neutral (to include all operating systems not just distributions of Linux)?
To svx's point, I think it's reasonable to rely entirely on a single distribution of Linux to use as a basis for building a complete set of documentation (wherein you'd obviously only mention that OS). To polyester's point, I think it's reasonable to want pragmatism e.g. relying on external sources.
The most obvious approach I see and would recommend is to let svx (the most active volunteer) complete his vision for non-neutral documentation (if I understand correctly) then analyze and open tickets regarding areas that the documentation falls short (e.g. "you didn't mention RPM here!") If the tickets pile up, you have a problem. If not, you don't (oversimplification). Audience is key, as polyester says but I would let svx's vision proliferate in the "real world" to get a sense of how his vision is perceived.
Lastly, to "avoid confusion" I think it is most important for the core team to publish official documentation that actively makes the distinction between "official" and "3rd party" approaches. In the best case scenario, the official documentation presents a clear and concise narrative (albeit potentially limited in scope) while "confusing" subjects are relegated to the wilds of 3rd party sources e.g. SO, et al.
What I am hearing is that @svx wants consistency and this is regardless of the outcome. I think consistency (which I wholeheartedly support) can be achieved in incorporting both @svx's and @polyester's views.
For in-depth topics, it seems appropriate to include instructions (or links) for other OS; for basic how-to-use-Plone docs, it isn't. However, the docs in general, should be written from the perspective of one widely used OS so:
User's aren't distracted or overwhelmed by documentation from completing their "task"
The docs as a whole don't become unwieldly with uncountable "branches" for every task in every possible OS, which is unsustainable
I think what we have is a visual and organizational problem, not a content problem.
Additional OS-specific instructions should be easy for users to find and easy for the Docs Team (or anyone really) to manage updates—they need to be visually separated from the how-to steps (for any given task).
This could be accomplished by @jensens idea, my woeful mockup below (just to show what I mean), or something else—however it best fits into @svx's vision. And on this last point, I agree with @aclark to "let svx's vision proliferate in the "real world" to get a sense of how his vision is perceived."
