Re: Docs

[Bill Farner <wf...@apache.org>]

I'd like to revisit this, since we gain a lot by exposing our docs in more
places (http://docs.cloudstack.apache.org/ is wonderful, we should
replicate that).  If this can indeed be automated, it seems like a huge
win.  I had not heard of pandoc before, it looks awesome!

*Sebastien* - a few questions for you, so we can learn from cloudstack:

- What is the motivation behind cloudstack's docs being in a separate
repository?

- I noticed the cloudstack repo uses .md and cloudstack-docs uses .rst, any
specific reasons for the difference?

- Is the .md -> .rst a requirement, or just preferable?  I'm not married to
.md, just curious what's at play.



-=Bill


On Tue, Feb 18, 2014 at 1:05 PM, Sebastien Goasguen <ru...@gmail.com>wrote:

>
> On Feb 18, 2014, at 9:42 AM, Jake Farrell <jf...@apache.org> wrote:
>
> > Based on what i've seen in other projects around the ASF I would say that
> > we should keep the docs on the core website and not external. This will
> > help the main websites seo and docs that are pushed externally tend to
> not
> > get updated as much as they are forgotten about.
> >
>
> My experience has been as committer on cloudstack and libcloud. IMHO the
> ASF content management system is a bit of a pain and still svn based.
> So while I tend to agree that the docs should be local to the site itself,
> readthedocs.org (RTD) provides some very interesting features, like
> github integration.
> This helps in getting new folks to contribute documentation because a pull
> request is just a click away.
>
> To your concerns, RTD does provide canonical URLs that help with SEO.
> Finally, the docs remain part of the same code repo and the doc site gets
> updated automatically on each commit. So there is nothing getting out of
> date. You edit the .rst files, and it gets published as soon as the github
> mirror sees the new commit.
>
> I personally think it's cool and looks good, but that's you guys's call.
>
> -sebastien
>
> > -Jake
> >
> >
> > On Mon, Feb 17, 2014 at 3:04 PM, Dave Lester <dave@ischool.berkeley.edu
> >wrote:
> >
> >> Sebastien,
> >>
> >> This is great, thank you!
> >>
> >> There were a few bugs in our existing tooling for rendering docs on the
> >> site which has prevented rendering the docs as-is (delayed on part;
> >> although JakeF offered to help). I am inclined to switch entirely to
> what
> >> you've contributed here seeing -- what do others think?
> >>
> >> A few questions this
> >>
> >> * Are folks ok with a switch from markdown to rst?
> >> * Can this handle translated docs as well? Long-term we may want that.
> >> * Can we automate the generation of these docs? The solution we were
> close
> >> to going live with was a simple rake command.
> >>
> >> Thanks again,
> >>
> >> Dave
> >>
> >> On Monday, February 17, 2014, sebgoa <ru...@gmail.com> wrote:
> >>
> >>> Hi,
> >>>
> >>> Since I was testing aurora today I noticed there was no documentation
> >> site
> >>> that I could see, other than the markdown files in the repo.
> >>>
> >>> So I went ahead and did a little prototype for you:
> >>>
> >>> http://apache-aurora-incubating.readthedocs.org/en/latest/index.html
> >>>
> >>> I am using this for CloudStack and it's also used for Apache libcloud.
> >>> It uses sphinx to organize docs, it's based on restructured text which
> is
> >>> fairly close to markdown.
> >>> It can be built on the fly thanks to a service hook on the github
> mirror
> >>> It's hosted by readthedocs.
> >>> It generates epub, pdf and can manage releases.
> >>>
> >>> You can see how I reorganize the tree at:
> >>>
> >>> https://github.com/runseb/incubator-aurora/tree/master/docs
> >>>
> >>> I took the existing markdown files and converted everything to .rst
> using
> >>> pandoc. There are a few gotchas here and there that need to be fixed.
> >>>
> >>> Let me know if that's something that would be of interest, I would be
> >>> happy to clean it up and organize the content to have a proper TOC and
> >> then
> >>> submit a patch.
> >>>
> >>> Cheers,
> >>>
> >>> -Sebastien
> >>
>
>

Re: Docs

[Sebastien Goasguen <ru...@gmail.com>]

On Apr 8, 2014, at 2:22 PM, Bill Farner <wf...@apache.org> wrote:

> I'd like to revisit this, since we gain a lot by exposing our docs in more places (http://docs.cloudstack.apache.org/ is wonderful, we should replicate that).  If this can indeed be automated, it seems like a huge win.  I had not heard of pandoc before, it looks awesome!
> 
> Sebastien - a few questions for you, so we can learn from cloudstack:
> 
> - What is the motivation behind cloudstack's docs being in a separate repository?

It allows us to have separate releases for docs and code and especially different release cycles. Our users complained that if an error was found in the docs and that we only released docs when we released code, it could be 4 months before a doc correction got propagated. We now can create doc releases but we can also easily serve the docs that are in master.
 
We could have kept the docs in the same repo, that was basically a community decision. Also note that we have ~400 pages of docs.

Libcloud does not do this, they use readthedocs as well but have not split their repo.


> 
> - I noticed the cloudstack repo uses .md and cloudstack-docs uses .rst, any specific reasons for the difference?
> 

Yeah, don't pay attention to this :) that's not quite right, the main documentation is in .rst .

> - Is the .md -> .rst a requirement, or just preferable?  I'm not married to .md, just curious what's at play.
> 

.rst is what's used by readthedocs.org , so we moved to .rst. Originally we used docbook format and publican to build our docs (like redhat and fedora). readthedocs might provide markdown support in the near future.

But really the biggest reasons to change format and host our docs with readthedocs were:

- That the build of our docs was a pain and the CMS on apache infra is not great.
- We wanted to provide an easy way for folks to contribute. Changing format from docbook to .rst made it easy for people to write docs. Using readthedocs gave us a great integration with github, so people can submit pull request on the fly. Once we make the commit, the docs are automatically updated on the site.



> 
> 
> -=Bill
> 
> 
> On Tue, Feb 18, 2014 at 1:05 PM, Sebastien Goasguen <ru...@gmail.com> wrote:
> 
> On Feb 18, 2014, at 9:42 AM, Jake Farrell <jf...@apache.org> wrote:
> 
> > Based on what i've seen in other projects around the ASF I would say that
> > we should keep the docs on the core website and not external. This will
> > help the main websites seo and docs that are pushed externally tend to not
> > get updated as much as they are forgotten about.
> >
> 
> My experience has been as committer on cloudstack and libcloud. IMHO the ASF content management system is a bit of a pain and still svn based.
> So while I tend to agree that the docs should be local to the site itself, readthedocs.org (RTD) provides some very interesting features, like github integration.
> This helps in getting new folks to contribute documentation because a pull request is just a click away.
> 
> To your concerns, RTD does provide canonical URLs that help with SEO.
> Finally, the docs remain part of the same code repo and the doc site gets updated automatically on each commit. So there is nothing getting out of date. You edit the .rst files, and it gets published as soon as the github mirror sees the new commit.
> 
> I personally think it's cool and looks good, but that's you guys's call.
> 
> -sebastien
> 
> > -Jake
> >
> >
> > On Mon, Feb 17, 2014 at 3:04 PM, Dave Lester <da...@ischool.berkeley.edu>wrote:
> >
> >> Sebastien,
> >>
> >> This is great, thank you!
> >>
> >> There were a few bugs in our existing tooling for rendering docs on the
> >> site which has prevented rendering the docs as-is (delayed on part;
> >> although JakeF offered to help). I am inclined to switch entirely to what
> >> you've contributed here seeing -- what do others think?
> >>
> >> A few questions this
> >>
> >> * Are folks ok with a switch from markdown to rst?
> >> * Can this handle translated docs as well? Long-term we may want that.
> >> * Can we automate the generation of these docs? The solution we were close
> >> to going live with was a simple rake command.
> >>
> >> Thanks again,
> >>
> >> Dave
> >>
> >> On Monday, February 17, 2014, sebgoa <ru...@gmail.com> wrote:
> >>
> >>> Hi,
> >>>
> >>> Since I was testing aurora today I noticed there was no documentation
> >> site
> >>> that I could see, other than the markdown files in the repo.
> >>>
> >>> So I went ahead and did a little prototype for you:
> >>>
> >>> http://apache-aurora-incubating.readthedocs.org/en/latest/index.html
> >>>
> >>> I am using this for CloudStack and it's also used for Apache libcloud.
> >>> It uses sphinx to organize docs, it's based on restructured text which is
> >>> fairly close to markdown.
> >>> It can be built on the fly thanks to a service hook on the github mirror
> >>> It's hosted by readthedocs.
> >>> It generates epub, pdf and can manage releases.
> >>>
> >>> You can see how I reorganize the tree at:
> >>>
> >>> https://github.com/runseb/incubator-aurora/tree/master/docs
> >>>
> >>> I took the existing markdown files and converted everything to .rst using
> >>> pandoc. There are a few gotchas here and there that need to be fixed.
> >>>
> >>> Let me know if that's something that would be of interest, I would be
> >>> happy to clean it up and organize the content to have a proper TOC and
> >> then
> >>> submit a patch.
> >>>
> >>> Cheers,
> >>>
> >>> -Sebastien
> >>
> 
>