Re: cURRENT uSER gUID XTATUS

[Emmanuel Lécharny]

I'm currently reworking the Security part, and AFAICT, here are the
chapters that need to be written :


*  [5.1 - SSL (e)](user-guide/5.1-ssl.html)
*  [5.2 - StartTLS (e)](user-guide/5.2-start-tls.html)
*  [5.3 - Password handling](user-guide/5.3-password-handling.html)
*  [5.4 - SASL Bind](user-guide/5.4-sasl-bind.html)
*  [5.5 - Certificates](user-guide/5.5-certificates.html)
*  [5.6 - ACI and ACLs (e)](user-guide/5.6-aci-and-acls.html)

The last one on ACL/ACIs will only be an introduction, as there is
nothing really available atm in the API.


- SSL is about...SSL ;-)

- StartTLS will explain hw to start a TLS communication and what it implies

- Password section is about the changePassword operation

- Certificates is about authent using certificates


I may not add some of those sections if there is not enough meat in teh
API to cover them properly, so consider that to be just a proposal.


Please feel free to comment or add anything that you think should be
covered.

Here is the introduction on security :
http://directory.staging.apache.org/api/user-guide/5-ldap-security.html


Le 01/01/2017 à 16:31, Shawn McKinney a écrit :
>> On Jan 1, 2017, at 5:04 AM, Emmanuel Lécharny  wrote:
>>
>> now that you have spent some time reading and fixing the current (and
>> incomplete) DLAP API User Guide, do you have any general remark related
>> to its content, structure, or whatever ?
>>
> Overall structure is pretty good.  It’s broken down in a reasonable way -- 
> basic, advanced, etc, and the subsections are ordered well.  Nav is easy 
> enough although a (master) table of contents listing all of the pages, 
> descriptions and status (finished or not) would be helpful.
>
> Content is mixed.  What’s there is quite good but many things not covered.  
> For example, security isn't covered.  Of course I suggest it be completed 
> ASAP.  To be fair authN’s covered in the bind/unbind section but SSL/TLS & 
> authZ isn't. 
>
> We need our code samples to be downloadable.  One of my fav LDAP books, “LDAP 
> Programming with Java” (Weltman, Dahbura) was released before Internet code 
> dist was the norm but nevertheless included a CD containing all of the code 
> samples.  I literally built my first 5 LDAP programs with these examples.  
> The book is probably one of the reasons the Netscape Java LDAP API gained 
> popularity.
>
> Perhaps we start a github project that includes samples such as this.  Or, 
> even manage a new repo in our project?
>
> Thanks,
> Shawn

-- 
Emmanuel Lecharny

Symas.com
directory.apache.org

Re: cURRENT uSER gUID XTATUS

[Shawn McKinney]

Started wiki page: https://en.wikipedia.org/wiki/Apache_ldap_api

(needs a little love)

Shawn

> On Jan 1, 2017, at 12:07 PM, Emmanuel Lécharny  wrote:
> 
> 
> 
> Le 01/01/2017 à 16:31, Shawn McKinney a écrit :
>>> On Jan 1, 2017, at 5:04 AM, Emmanuel Lécharny  wrote:
>>> 
>>> now that you have spent some time reading and fixing the current (and
>>> incomplete) DLAP API User Guide, do you have any general remark related
>>> to its content, structure, or whatever ?
>>> 
>> Overall structure is pretty good.  It’s broken down in a reasonable way -- 
>> basic, advanced, etc, and the subsections are ordered well.  Nav is easy 
>> enough although a (master) table of contents listing all of the pages, 
>> descriptions and status (finished or not) would be helpful.
>> 
>> Content is mixed.  What’s there is quite good but many things not covered.  
>> For example, security isn't covered.  Of course I suggest it be completed 
>> ASAP.  To be fair authN’s covered in the bind/unbind section but SSL/TLS & 
>> authZ isn't. 
> 
> On my list for next week. Call it a new year good resolution :-)
> 
> -- 
> Emmanuel Lecharny
> 
> Symas.com
> directory.apache.org
> 

Re: cURRENT uSER gUID XTATUS

[Emmanuel Lécharny]

Le 01/01/2017 à 16:31, Shawn McKinney a écrit :
>> On Jan 1, 2017, at 5:04 AM, Emmanuel Lécharny  wrote:
>>
>> now that you have spent some time reading and fixing the current (and
>> incomplete) DLAP API User Guide, do you have any general remark related
>> to its content, structure, or whatever ?
>>
> Overall structure is pretty good.  It’s broken down in a reasonable way -- 
> basic, advanced, etc, and the subsections are ordered well.  Nav is easy 
> enough although a (master) table of contents listing all of the pages, 
> descriptions and status (finished or not) would be helpful.
>
> Content is mixed.  What’s there is quite good but many things not covered.  
> For example, security isn't covered.  Of course I suggest it be completed 
> ASAP.  To be fair authN’s covered in the bind/unbind section but SSL/TLS & 
> authZ isn't. 

On my list for next week. Call it a new year good resolution :-)

-- 
Emmanuel Lecharny

Symas.com
directory.apache.org

Re: LDAP API 1.0-GA preparation

[Emmanuel Lécharny]

Le 01/01/2017 à 16:47, Shawn McKinney a écrit :
>> On Jan 1, 2017, at 3:47 AM, Pierre Smits  wrote:
>>
>> First of all: Happy New Year. May it be an exciting and interesting one!
>>
>> It seems to me that having user guides as static pages we create the
>> impression that they are applicable to any version available to the
>> adopters of our products (old, superseded versions and the latest
>> available). We know that that isn't true. As our products evolve, so do our
>> user guides.
>>
>> Would it not be better to recreate the pages in our wiki and per page state
>> to which page they are applicable?
> Thanks Pierre, same to you!
>
> wrt recreation of pages:
>
> It’s good to have content available both online/offline and that’s easy to 
> use.  If we were to move away from the website I’d point towards the markdown 
> format (.md), popularized on github projects rather than yet another HTML 
> website format (wiki).

The current format is markdown, even if the file extension is .mdtext.
>
> But, the act of moving a document this large will consume a lot of time and 
> I’m not convinced it’s where we should be spending our time.

I'd rather complete what we have, then try t produce a pdf out of it
should be easy.
>
> The most important thing is the content is captured in one place, and usable, 
> we can move it later, if need be.

indeed !

-- 
Emmanuel Lecharny

Symas.com
directory.apache.org

Re: LDAP API 1.0-GA preparation

[Shawn McKinney]

> On Jan 1, 2017, at 3:47 AM, Pierre Smits  wrote:
> 
> First of all: Happy New Year. May it be an exciting and interesting one!
> 
> It seems to me that having user guides as static pages we create the
> impression that they are applicable to any version available to the
> adopters of our products (old, superseded versions and the latest
> available). We know that that isn't true. As our products evolve, so do our
> user guides.
> 
> Would it not be better to recreate the pages in our wiki and per page state
> to which page they are applicable?

Thanks Pierre, same to you!

wrt recreation of pages:

It’s good to have content available both online/offline and that’s easy to use. 
 If we were to move away from the website I’d point towards the markdown format 
(.md), popularized on github projects rather than yet another HTML website 
format (wiki).

But, the act of moving a document this large will consume a lot of time and I’m 
not convinced it’s where we should be spending our time.

The most important thing is the content is captured in one place, and usable, 
we can move it later, if need be.

Thanks,
Shawn

Re: cURRENT uSER gUID XTATUS

[Shawn McKinney]

> On Jan 1, 2017, at 5:04 AM, Emmanuel Lécharny  wrote:
> 
> now that you have spent some time reading and fixing the current (and
> incomplete) DLAP API User Guide, do you have any general remark related
> to its content, structure, or whatever ?
> 

Overall structure is pretty good.  It’s broken down in a reasonable way -- 
basic, advanced, etc, and the subsections are ordered well.  Nav is easy enough 
although a (master) table of contents listing all of the pages, descriptions 
and status (finished or not) would be helpful.

Content is mixed.  What’s there is quite good but many things not covered.  For 
example, security isn't covered.  Of course I suggest it be completed ASAP.  To 
be fair authN’s covered in the bind/unbind section but SSL/TLS & authZ isn't. 

We need our code samples to be downloadable.  One of my fav LDAP books, “LDAP 
Programming with Java” (Weltman, Dahbura) was released before Internet code 
dist was the norm but nevertheless included a CD containing all of the code 
samples.  I literally built my first 5 LDAP programs with these examples.  The 
book is probably one of the reasons the Netscape Java LDAP API gained 
popularity.

Perhaps we start a github project that includes samples such as this.  Or, even 
manage a new repo in our project?

Thanks,
Shawn

cURRENT uSER gUID XTATUS

[Emmanuel Lécharny]

Hi Shawn !


now that you have spent some time reading and fixing the current (and
incomplete) DLAP API User Guide, do you have any general remark related
to its content, structure, or whatever ?


Many thanks !


-- 
Emmanuel Lecharny

Symas.com
directory.apache.org

Re: LDAP API 1.0-GA preparation

[Emmanuel Lécharny]

Thanks a lot, Shawn ! Great job !



Le 01/01/2017 à 10:47, Pierre Smits a écrit :
> Great work, Shawn,
>
> First of all: Happy New Year. May it be an exciting and interesting one!
>
> It seems to me that having user guides as static pages we create the
> impression that they are applicable to any version available to the
> adopters of our products (old, superseded versions and the latest
> available). We know that that isn't true. As our products evolve, so do our
> user guides.
Actually, that will be true when we will have reached teh first official
GA, which is not currently the case.

As soon as we start working on a 2.0 (which has already started, FTR,
then the UserGuide will have to be distinct.

-- 
Emmanuel Lecharny

Symas.com
directory.apache.org

Re: LDAP API 1.0-GA preparation

[Pierre Smits]

Great work, Shawn,

First of all: Happy New Year. May it be an exciting and interesting one!

It seems to me that having user guides as static pages we create the
impression that they are applicable to any version available to the
adopters of our products (old, superseded versions and the latest
available). We know that that isn't true. As our products evolve, so do our
user guides.

Would it not be better to recreate the pages in our wiki and per page state
to which page they are applicable?

Best regards,

Pierre Smits

ORRTIZ.COM 
OFBiz based solutions & services

OFBiz Extensions Marketplace
http://oem.ofbizci.net/oci-2/

On Sat, Dec 31, 2016 at 7:00 PM, Shawn McKinney 
wrote:

>
> > On Dec 18, 2016, at 11:54 AM, Emmanuel Lécharny 
> wrote:
> >
> > Obviously, there is a lot of thing to add... I think the structure might
> > also be improved. Anyway, we have something to start with...
> >
> > If you feel like to start reviewing the completed pages, please do so !
>
> Hello,
>
> I have completed a first-pass over our LDAP API’s user guide.  The goal
> was to cleanup grammar, spelling, description semantics, and broken links.
> I didn’t add new content, nor did I alter the structure of any of existing
> documents.
>
> There are many sections not yet completed but I believe we’re OK for a 1.0
> GA (although the security sections should be completed soon for obvious
> reasons).
>
> You can review the updated user’s guide here:
> http://directory.staging.apache.org/api/user-guide.html
>
> I really like the story.  It should be emphasized once this release
> becomes public:
> http://directory.staging.apache.org/api/user-guide/1.3-
> apache-ldap-api-rational.html
>
> At the very least we should create a wikipedia page with this as its
> history.
>
> Let me know if you see any errors that need correcting.
>
> Thanks,
> Shawn