You are viewing a plain text version of this content. The canonical link for it is here.
Posted to api@directory.apache.org by Pierre Smits <pi...@gmail.com> on 2017/01/01 09:47:33 UTC
Re: LDAP API 1.0-GA preparation
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 <http://www.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 <sm...@apache.org>
wrote:
>
> > On Dec 18, 2016, at 11:54 AM, Emmanuel Lécharny <el...@gmail.com>
> 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
Re: LDAP API 1.0-GA preparation
Posted by Emmanuel Lécharny <el...@gmail.com>.
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
Posted by Emmanuel Lécharny <el...@gmail.com>.
Le 01/01/2017 à 16:47, Shawn McKinney a écrit :
>> On Jan 1, 2017, at 3:47 AM, Pierre Smits <pi...@gmail.com> 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
Posted by Shawn McKinney <sm...@apache.org>.
> On Jan 1, 2017, at 3:47 AM, Pierre Smits <pi...@gmail.com> 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