Daniel Howard wrote:

My recent experience is OpenLDAP on Ubuntu. I thought I would go with OpenLDAP's guide because they should know better, but the quick start was for older versions or something and hadn't been updated.

I like documentation systems that allow for user feedback, comments, or patches via github.

Sorry, that will never happen. We use git, and we use github, but we will never rely on github. It is too much of a SPOF in the open source ecosystem and far too juicy an attack target.

If you want community improvements then maybe low hanging fruit is a link in the doc template on how to interact with the documentation.... If the current docs platform has no mechanism for feedback and comments on a specific document, the source code/ build process is obscure ... Maybe consider porting even a "fork " to github and solicit community feedback (you can file issues in a familiar mechanism, and take in patches from dudes like me...)

For what it's worth, the Ubuntu OpenLDAP quick start guide and only a few minor hiccups, and I would recommend that resource for anyone looking to implement or update a quickstart guide.

The Faq-o-Matic ... Man a modern stack overflow site might be nice but a question in the back of my mind is whether the advice is still useful. I don't know if the FoM does this but if the answers showed dates

Of course it can.

then I could evaluate an answer that's say 2-4 years old with greater confidence than say something 12 years old ...

I agree with you there. But I already have dates/attributions enabled in my FoM profile.

One of the challenges of a venerable, old and mature project like OpenLDAP.

No, one of the challenges of a modern population that doesn't take the effort to read. Frankly, that population is a waste of time.

I guess what I'm trying to say, from my mobile phone, is if the documentation were more "agile" in engaging the community for identifying issues and taking in corrections, we may all be happier.

The process of creating a patch with git is the same, whether we use github or not. I don't believe that's particularly meaningful.

I would be open to volunteering to port docs...

Thanks, -Danny

-- Sent from my Western Electric Model 500

On Apr 29, 2016 5:01 PM, "Gavin Henry" <ghenry@openldap.org mailto:ghenry@openldap.org> wrote:

Hi all,

List what you love about our docs:

List what you hate:

List what you'd love to see:

List what you can help with:

Thanks.

--
Kind Regards,
Gavin Henry.

On 04/30/2016 09:04 PM, Howard Chu wrote:

The process of creating a patch with git is the same, whether we use github or not. I don't believe that's particularly meaningful.

My thoughts exactly. Some 3-4 years ago. Then I've actually tried to run a project on github. It siginificanly lowers the contribution barrier. It is much easier to press "pull request" button than to bundle the patch in command-line, send it to the mailing list (subscribe there first), then wait for the maintainer, check all the time whether the patch was merged, ...

Github-like approach makes a big difference. I see it in midPoint (which I'm maintianing) and I see it in ConnId (where I'm regularly contributing). I also see how bad it is without github for several Apache projects that I watch closely. And I will probably never contribute to these (unless I really have to) because the overhead is so high.

To state that openly: I would probably never contribute to OpenLDAP documentation if I have to bundle a patch in a mail to a mailing list. I'm quite likely to contribute if there is a convenient "pull request" button or if it is maintained in a wiki.

We are running the midPoint project on github for several years. But I'm not afraid. I can still check all the code changes in any git tool I like. As a maintainer you do not need to rely on github. And if github would disappear at this very moment we will be running on a different site before the day is over. With no loss in the source code history. This is git, the migration is really trivial. So I believe that the benefits greatly outweigh the risks.

If you do not like github go for gitlab. You can even host that yourself.

On 05/02/2016 01:52 PM, Howard Chu wrote:

Patch submission does not require subscribing to a mailing list. Submission to the ITS doesn't require an account/signup at all. There is no such contribution barrier. In contrast, any system that requires creating an account first is a significant barrier, IME.

Mailing list and github-like submissions are not mutually exclusive. What I am asking for is an additional method for submitting contributions. I do not ask to stop the mail-based submission process.

I've used both methods. And I fully accept that preferences may vary. According to my personal experience github-like method is more convenient and I perceive it as a (much) lower barrier than mailing a patch. Huge number of developers already have github accounts, so there is no additional barrier for these people. I would definitely prefer the github option if it was available. And obviously I'm not alone. This is may not be strictly about technicalities. It may be more about the subjective perception of the contributors. Gavin asked for feedback so I am providing humble subjective feedback of a potential contributor. Exactly as requested.

The majority of submitters are "fire and forget" - nobody is checking back frequently to see what happened to their submission.

True. But if I'm contributing I want to know whether my contribution made it to the main code base. At the very least. I would like to know whether I still need to maintain my private fork or whether I can switch to the primary code base. If the contribution was rejected I would like to know why it was rejected and what I need to improve for the contribution to be accepted. Github tracks the contribution process, allows to discuss the contribution and sends notification mails. Very convenient.

On 05/02/2016 03:45 PM, Howard Chu wrote:

You seem to be entirely missing the point, which I have been trying to clarify, that OpenLDAP ITS submissions are not mail-based, so none of this point is even relevant.

Yes, you are right. Sorry for that. But I do not think I'm missing the point. If I have to find may way through yet another custom process that this particular project has set up to submit a documentation fix then I simply won't do that. Whether it is a mailing list or it is an issue tracking system that I have never seen before does not really make much difference. If there is a way how to contribute by using convenient tools that I already know then the probability is much higher. And a good part of potential contributors already know github. That's my point. Take it or leave it.