You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@zookeeper.apache.org by Patrick Hunt <ph...@apache.org> on 2017/12/07 04:45:52 UTC
Documentation improvements proposal for ZK
Hi folks. Now that we've gotten the website issues straightened out I
looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics
and make it easier for people to generate and maintain the docs.
Given we're using Jekyll/Markdown successfully for the site I tried
converting our current documentation (forrest/simpledocbook(xml)) into
Markdown using the same tooling I had originally developed for 925. It went
pretty smoothly, pretty much looks the same as the forrest generated site,
but is much easier to work with:
1) markdown for the source doc format rather than xml
2) jekyll to generate the docs, same as the new site generation
I also looked at modernizing and streamlining our process around docs, in
particular:
1) src/docs contains the jekyll/markdown based source. Basically the same
as before with forrest/sdb but much easier to work with. e.g. consistent
with what folks are used to on github.
2) remove /docs from the source repository (git). Committers/contributors
no longer need to worry about committing the generated docs into /docs.
During active development we'd only be committing src/docs (the markdown)
and not /docs (the generated docs). As part of a release we'd still
generate a static copy of the docs and include in the release artifact, as
well as including on the website. The primary difference here is that the
docs on (git) branches would just be the source. Folks could checkout and
generate the source docs at any time using jekyll. Note that this is also
consistent with many other apache projects.
I believe this would be a significant improvement to our current experience
around documentation, please take a look at the following branch to get
some insight:
https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
Here you can see the original .xml files side-by-side with the markdown
formatted docs, in a jekyll based environment. The markdown formatted files
having been converted using a variant of the script attached to 925. It's
99% there - still a bit of hand editing necessary to address the corner
cases (typically odd/broken formatting in the current doc). You can "jekyll
build" same as the site (in src/docs) if you would like to see the
generation process itself.
If we go ahead with this we'd need to port this to our active branches -
3.4/3.5 and master. (the example branch I linked to is just master).
Everyone please take a look and LMK if you have any concerns. Committers
please +1 if you agree, comments otw.
Regards,
Patrick
Re: Documentation improvements proposal for ZK
Posted by Patrick Hunt <ph...@apache.org>.
Not sure if it's a coincidence - but notice that those two .md files are
the largest two markdown files of the set.... Perhaps it's a size issue?
Patrick
On Thu, Dec 7, 2017 at 3:27 PM, Patrick Hunt <ph...@apache.org> wrote:
> That's a very cool service, thanks for the pointer Tamas!
>
> I noticed a link down the bottom to "report issues", however it doesn't
> seem like the project is still being maintained, e.g.:
> https://github.com/adamburmister/gitprint.com/issues/63
>
> Perhaps you could try running this tool against the page yourself (not
> using the service) such that you can get the debugging output? I'm afraid I
> don't know where I'd start, the site is giving no information on the
> failure. LMK and I'll update the content.
>
> I did run mdl (markdown lint) on the .md files and noticed it highlighted
> some issues, Nothing looked particularly serious (e.g. in programmers) and
> I haven't gotten around to cleaning those up given I haven't moved over to
> that phase yet (still tweaking the conversion script).
>
> Thanks!
>
> Patrick
>
>
> On Thu, Dec 7, 2017 at 1:35 PM, Tamas Penzes <ta...@cloudera.com> wrote:
>
>> Hi Patrick,
>>
>> I like the converted documents, much better than the XML solution because
>> easy to read and easy to edit (from developer point of view).
>> I have also checked the files one by one with gitprint and found two,
>> which
>> it cannot display:
>>
>> https://github.com/phunt/zookeeper/blob/jekyll-docs/src/
>> docs/zookeeperAdmin.md
>> -->
>> https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/
>> docs/zookeeperAdmin.md
>>
>> https://github.com/phunt/zookeeper/blob/jekyll-docs/src/
>> docs/zookeeperProgrammers.md
>> -->
>> https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/
>> docs/zookeeperProgrammers.md
>>
>> Since they are rendered properly (as far as I see) on github webpage, just
>> the PDF conversion fails with gitprint I don't know where the problem is.
>> Still it would be useful if it worked, so anyone with web access could
>> generate PDFs on-the-fly with the use of gitprint for themselves.
>>
>> Regards, Tamaas
>>
>> On Thu, Dec 7, 2017 at 5:45 AM, Patrick Hunt <ph...@apache.org> wrote:
>>
>> > Hi folks. Now that we've gotten the website issues straightened out I
>> > looked back at ZOOKEEPER-925 with an eye toward simplifying our
>> mechanics
>> > and make it easier for people to generate and maintain the docs.
>> >
>> > Given we're using Jekyll/Markdown successfully for the site I tried
>> > converting our current documentation (forrest/simpledocbook(xml)) into
>> > Markdown using the same tooling I had originally developed for 925. It
>> went
>> > pretty smoothly, pretty much looks the same as the forrest generated
>> site,
>> > but is much easier to work with:
>> >
>> > 1) markdown for the source doc format rather than xml
>> > 2) jekyll to generate the docs, same as the new site generation
>> >
>> > I also looked at modernizing and streamlining our process around docs,
>> in
>> > particular:
>> >
>> > 1) src/docs contains the jekyll/markdown based source. Basically the
>> same
>> > as before with forrest/sdb but much easier to work with. e.g. consistent
>> > with what folks are used to on github.
>> >
>> > 2) remove /docs from the source repository (git).
>> Committers/contributors
>> > no longer need to worry about committing the generated docs into /docs.
>> > During active development we'd only be committing src/docs (the
>> markdown)
>> > and not /docs (the generated docs). As part of a release we'd still
>> > generate a static copy of the docs and include in the release artifact,
>> as
>> > well as including on the website. The primary difference here is that
>> the
>> > docs on (git) branches would just be the source. Folks could checkout
>> and
>> > generate the source docs at any time using jekyll. Note that this is
>> also
>> > consistent with many other apache projects.
>> >
>> > I believe this would be a significant improvement to our current
>> experience
>> > around documentation, please take a look at the following branch to get
>> > some insight:
>> >
>> > https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
>> > Here you can see the original .xml files side-by-side with the markdown
>> > formatted docs, in a jekyll based environment. The markdown formatted
>> files
>> > having been converted using a variant of the script attached to 925.
>> It's
>> > 99% there - still a bit of hand editing necessary to address the corner
>> > cases (typically odd/broken formatting in the current doc). You can
>> "jekyll
>> > build" same as the site (in src/docs) if you would like to see the
>> > generation process itself.
>> >
>> > If we go ahead with this we'd need to port this to our active branches -
>> > 3.4/3.5 and master. (the example branch I linked to is just master).
>> >
>> > Everyone please take a look and LMK if you have any concerns. Committers
>> > please +1 if you agree, comments otw.
>> >
>> > Regards,
>> >
>> > Patrick
>> >
>>
>>
>>
>> --
>>
>> *Tamás **Pénzes* | Engineering Manager
>> e. tamaas@cloudera.com
>> cloudera.com <http://www.cloudera.com/>
>>
>> [image: Cloudera] <http://www.cloudera.com/>
>>
>> [image: Cloudera on Twitter] <https://twitter.com/cloudera> [image:
>> Cloudera on Facebook] <https://www.facebook.com/cloudera> [image:
>> Cloudera
>> on LinkedIn] <https://www.linkedin.com/company/cloudera>
>> ------------------------------
>>
>
>
Re: Documentation improvements proposal for ZK
Posted by Patrick Hunt <ph...@apache.org>.
That's a very cool service, thanks for the pointer Tamas!
I noticed a link down the bottom to "report issues", however it doesn't
seem like the project is still being maintained, e.g.:
https://github.com/adamburmister/gitprint.com/issues/63
Perhaps you could try running this tool against the page yourself (not
using the service) such that you can get the debugging output? I'm afraid I
don't know where I'd start, the site is giving no information on the
failure. LMK and I'll update the content.
I did run mdl (markdown lint) on the .md files and noticed it highlighted
some issues, Nothing looked particularly serious (e.g. in programmers) and
I haven't gotten around to cleaning those up given I haven't moved over to
that phase yet (still tweaking the conversion script).
Thanks!
Patrick
On Thu, Dec 7, 2017 at 1:35 PM, Tamas Penzes <ta...@cloudera.com> wrote:
> Hi Patrick,
>
> I like the converted documents, much better than the XML solution because
> easy to read and easy to edit (from developer point of view).
> I have also checked the files one by one with gitprint and found two, which
> it cannot display:
>
> https://github.com/phunt/zookeeper/blob/jekyll-docs/
> src/docs/zookeeperAdmin.md
> -->
> https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/
> src/docs/zookeeperAdmin.md
>
> https://github.com/phunt/zookeeper/blob/jekyll-docs/
> src/docs/zookeeperProgrammers.md
> -->
> https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/
> src/docs/zookeeperProgrammers.md
>
> Since they are rendered properly (as far as I see) on github webpage, just
> the PDF conversion fails with gitprint I don't know where the problem is.
> Still it would be useful if it worked, so anyone with web access could
> generate PDFs on-the-fly with the use of gitprint for themselves.
>
> Regards, Tamaas
>
> On Thu, Dec 7, 2017 at 5:45 AM, Patrick Hunt <ph...@apache.org> wrote:
>
> > Hi folks. Now that we've gotten the website issues straightened out I
> > looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics
> > and make it easier for people to generate and maintain the docs.
> >
> > Given we're using Jekyll/Markdown successfully for the site I tried
> > converting our current documentation (forrest/simpledocbook(xml)) into
> > Markdown using the same tooling I had originally developed for 925. It
> went
> > pretty smoothly, pretty much looks the same as the forrest generated
> site,
> > but is much easier to work with:
> >
> > 1) markdown for the source doc format rather than xml
> > 2) jekyll to generate the docs, same as the new site generation
> >
> > I also looked at modernizing and streamlining our process around docs, in
> > particular:
> >
> > 1) src/docs contains the jekyll/markdown based source. Basically the same
> > as before with forrest/sdb but much easier to work with. e.g. consistent
> > with what folks are used to on github.
> >
> > 2) remove /docs from the source repository (git). Committers/contributors
> > no longer need to worry about committing the generated docs into /docs.
> > During active development we'd only be committing src/docs (the markdown)
> > and not /docs (the generated docs). As part of a release we'd still
> > generate a static copy of the docs and include in the release artifact,
> as
> > well as including on the website. The primary difference here is that the
> > docs on (git) branches would just be the source. Folks could checkout and
> > generate the source docs at any time using jekyll. Note that this is also
> > consistent with many other apache projects.
> >
> > I believe this would be a significant improvement to our current
> experience
> > around documentation, please take a look at the following branch to get
> > some insight:
> >
> > https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
> > Here you can see the original .xml files side-by-side with the markdown
> > formatted docs, in a jekyll based environment. The markdown formatted
> files
> > having been converted using a variant of the script attached to 925. It's
> > 99% there - still a bit of hand editing necessary to address the corner
> > cases (typically odd/broken formatting in the current doc). You can
> "jekyll
> > build" same as the site (in src/docs) if you would like to see the
> > generation process itself.
> >
> > If we go ahead with this we'd need to port this to our active branches -
> > 3.4/3.5 and master. (the example branch I linked to is just master).
> >
> > Everyone please take a look and LMK if you have any concerns. Committers
> > please +1 if you agree, comments otw.
> >
> > Regards,
> >
> > Patrick
> >
>
>
>
> --
>
> *Tamás **Pénzes* | Engineering Manager
> e. tamaas@cloudera.com
> cloudera.com <http://www.cloudera.com/>
>
> [image: Cloudera] <http://www.cloudera.com/>
>
> [image: Cloudera on Twitter] <https://twitter.com/cloudera> [image:
> Cloudera on Facebook] <https://www.facebook.com/cloudera> [image: Cloudera
> on LinkedIn] <https://www.linkedin.com/company/cloudera>
> ------------------------------
>
Re: Documentation improvements proposal for ZK
Posted by Tamas Penzes <ta...@cloudera.com>.
Hi Patrick,
I like the converted documents, much better than the XML solution because
easy to read and easy to edit (from developer point of view).
I have also checked the files one by one with gitprint and found two, which
it cannot display:
https://github.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperAdmin.md
-->
https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperAdmin.md
https://github.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperProgrammers.md
-->
https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperProgrammers.md
Since they are rendered properly (as far as I see) on github webpage, just
the PDF conversion fails with gitprint I don't know where the problem is.
Still it would be useful if it worked, so anyone with web access could
generate PDFs on-the-fly with the use of gitprint for themselves.
Regards, Tamaas
On Thu, Dec 7, 2017 at 5:45 AM, Patrick Hunt <ph...@apache.org> wrote:
> Hi folks. Now that we've gotten the website issues straightened out I
> looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics
> and make it easier for people to generate and maintain the docs.
>
> Given we're using Jekyll/Markdown successfully for the site I tried
> converting our current documentation (forrest/simpledocbook(xml)) into
> Markdown using the same tooling I had originally developed for 925. It went
> pretty smoothly, pretty much looks the same as the forrest generated site,
> but is much easier to work with:
>
> 1) markdown for the source doc format rather than xml
> 2) jekyll to generate the docs, same as the new site generation
>
> I also looked at modernizing and streamlining our process around docs, in
> particular:
>
> 1) src/docs contains the jekyll/markdown based source. Basically the same
> as before with forrest/sdb but much easier to work with. e.g. consistent
> with what folks are used to on github.
>
> 2) remove /docs from the source repository (git). Committers/contributors
> no longer need to worry about committing the generated docs into /docs.
> During active development we'd only be committing src/docs (the markdown)
> and not /docs (the generated docs). As part of a release we'd still
> generate a static copy of the docs and include in the release artifact, as
> well as including on the website. The primary difference here is that the
> docs on (git) branches would just be the source. Folks could checkout and
> generate the source docs at any time using jekyll. Note that this is also
> consistent with many other apache projects.
>
> I believe this would be a significant improvement to our current experience
> around documentation, please take a look at the following branch to get
> some insight:
>
> https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
> Here you can see the original .xml files side-by-side with the markdown
> formatted docs, in a jekyll based environment. The markdown formatted files
> having been converted using a variant of the script attached to 925. It's
> 99% there - still a bit of hand editing necessary to address the corner
> cases (typically odd/broken formatting in the current doc). You can "jekyll
> build" same as the site (in src/docs) if you would like to see the
> generation process itself.
>
> If we go ahead with this we'd need to port this to our active branches -
> 3.4/3.5 and master. (the example branch I linked to is just master).
>
> Everyone please take a look and LMK if you have any concerns. Committers
> please +1 if you agree, comments otw.
>
> Regards,
>
> Patrick
>
--
*Tamás **Pénzes* | Engineering Manager
e. tamaas@cloudera.com
cloudera.com <http://www.cloudera.com/>
[image: Cloudera] <http://www.cloudera.com/>
[image: Cloudera on Twitter] <https://twitter.com/cloudera> [image:
Cloudera on Facebook] <https://www.facebook.com/cloudera> [image: Cloudera
on LinkedIn] <https://www.linkedin.com/company/cloudera>
------------------------------
Re: Documentation improvements proposal for ZK
Posted by Patrick Hunt <ph...@apache.org>.
Any other comments? I haven't seen any negative feedback so I'm going to
move ahead with this unless someone speaks up soon. :-)
Regards,
Patrick
On Tue, Dec 12, 2017 at 1:40 PM, Michael Han <ha...@apache.org> wrote:
> +1, this looks great, thanks for doing this Pat!
>
> On Wed, Dec 6, 2017 at 8:45 PM, Patrick Hunt <ph...@apache.org> wrote:
>
> > Hi folks. Now that we've gotten the website issues straightened out I
> > looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics
> > and make it easier for people to generate and maintain the docs.
> >
> > Given we're using Jekyll/Markdown successfully for the site I tried
> > converting our current documentation (forrest/simpledocbook(xml)) into
> > Markdown using the same tooling I had originally developed for 925. It
> went
> > pretty smoothly, pretty much looks the same as the forrest generated
> site,
> > but is much easier to work with:
> >
> > 1) markdown for the source doc format rather than xml
> > 2) jekyll to generate the docs, same as the new site generation
> >
> > I also looked at modernizing and streamlining our process around docs, in
> > particular:
> >
> > 1) src/docs contains the jekyll/markdown based source. Basically the same
> > as before with forrest/sdb but much easier to work with. e.g. consistent
> > with what folks are used to on github.
> >
> > 2) remove /docs from the source repository (git). Committers/contributors
> > no longer need to worry about committing the generated docs into /docs.
> > During active development we'd only be committing src/docs (the markdown)
> > and not /docs (the generated docs). As part of a release we'd still
> > generate a static copy of the docs and include in the release artifact,
> as
> > well as including on the website. The primary difference here is that the
> > docs on (git) branches would just be the source. Folks could checkout and
> > generate the source docs at any time using jekyll. Note that this is also
> > consistent with many other apache projects.
> >
> > I believe this would be a significant improvement to our current
> experience
> > around documentation, please take a look at the following branch to get
> > some insight:
> >
> > https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
> > Here you can see the original .xml files side-by-side with the markdown
> > formatted docs, in a jekyll based environment. The markdown formatted
> files
> > having been converted using a variant of the script attached to 925. It's
> > 99% there - still a bit of hand editing necessary to address the corner
> > cases (typically odd/broken formatting in the current doc). You can
> "jekyll
> > build" same as the site (in src/docs) if you would like to see the
> > generation process itself.
> >
> > If we go ahead with this we'd need to port this to our active branches -
> > 3.4/3.5 and master. (the example branch I linked to is just master).
> >
> > Everyone please take a look and LMK if you have any concerns. Committers
> > please +1 if you agree, comments otw.
> >
> > Regards,
> >
> > Patrick
> >
>
Re: Documentation improvements proposal for ZK
Posted by Michael Han <ha...@apache.org>.
+1, this looks great, thanks for doing this Pat!
On Wed, Dec 6, 2017 at 8:45 PM, Patrick Hunt <ph...@apache.org> wrote:
> Hi folks. Now that we've gotten the website issues straightened out I
> looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics
> and make it easier for people to generate and maintain the docs.
>
> Given we're using Jekyll/Markdown successfully for the site I tried
> converting our current documentation (forrest/simpledocbook(xml)) into
> Markdown using the same tooling I had originally developed for 925. It went
> pretty smoothly, pretty much looks the same as the forrest generated site,
> but is much easier to work with:
>
> 1) markdown for the source doc format rather than xml
> 2) jekyll to generate the docs, same as the new site generation
>
> I also looked at modernizing and streamlining our process around docs, in
> particular:
>
> 1) src/docs contains the jekyll/markdown based source. Basically the same
> as before with forrest/sdb but much easier to work with. e.g. consistent
> with what folks are used to on github.
>
> 2) remove /docs from the source repository (git). Committers/contributors
> no longer need to worry about committing the generated docs into /docs.
> During active development we'd only be committing src/docs (the markdown)
> and not /docs (the generated docs). As part of a release we'd still
> generate a static copy of the docs and include in the release artifact, as
> well as including on the website. The primary difference here is that the
> docs on (git) branches would just be the source. Folks could checkout and
> generate the source docs at any time using jekyll. Note that this is also
> consistent with many other apache projects.
>
> I believe this would be a significant improvement to our current experience
> around documentation, please take a look at the following branch to get
> some insight:
>
> https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs
> Here you can see the original .xml files side-by-side with the markdown
> formatted docs, in a jekyll based environment. The markdown formatted files
> having been converted using a variant of the script attached to 925. It's
> 99% there - still a bit of hand editing necessary to address the corner
> cases (typically odd/broken formatting in the current doc). You can "jekyll
> build" same as the site (in src/docs) if you would like to see the
> generation process itself.
>
> If we go ahead with this we'd need to port this to our active branches -
> 3.4/3.5 and master. (the example branch I linked to is just master).
>
> Everyone please take a look and LMK if you have any concerns. Committers
> please +1 if you agree, comments otw.
>
> Regards,
>
> Patrick
>