You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flume.apache.org by Jonathan Hsieh <jo...@cloudera.com> on 2011/07/19 23:43:11 UTC
[DISCUSS] Moving docs to Wiki.
Hey all,
I wanted to propose that we port the current documentation from its current
asciidoc form to the wiki. The documentation hasn't had a major structural
update for a while and from some of the lessons we've learned in the past
year it could use a refresh.
Here are the main trade offs that I currently have with this move.
Pro:
* Documentation will be easier for more people to modify and update.
* The move would simplify the build -- removing dependencies on several
packages including asciidoc, graphviz, syntax-highilght, and suffers from
version incompatiblity issues across different linux/windows/mac os's.
* By requiring design docs for major new features in the wiki, adding them
to the docs will require less effort.
Con:
* It will be more difficult to force code commits to make documentation
updates.
* Versioning documentation may become more of a hassle.
Lets discuss and when it peters out we can vote.
Thanks,
Jon.
--
// Jonathan Hsieh (shay)
// Software Engineer, Cloudera
// jon@cloudera.com
Re: [DISCUSS] Moving docs to Wiki.
Posted by Patrick Hunt <ph...@apache.org>.
On Tue, Jul 19, 2011 at 8:58 PM, Ralph Goers <ra...@dslextreme.com> wrote:
> Is there a reason not to use the Maven site plugin and generate documentation on the web site? I also have no problem with recommending the use of a CMS.
CMS is hooked into svnpubsub, so deployments are very fast.
http://www.apache.org/dev/cms.html#svnpubsub
Patrick
Re: [DISCUSS] Moving docs to Wiki.
Posted by Ralph Goers <ra...@dslextreme.com>.
I'm not sure I understand the issue around only having people who have file CLAs updating documentation. Anyone can create anything they want on a wiki. However, I would recommend against having formal documentation on the wiki for exactly that reason.
Is there a reason not to use the Maven site plugin and generate documentation on the web site? I also have no problem with recommending the use of a CMS.
Ralph
On Jul 19, 2011, at 3:04 PM, Tom White wrote:
> I agree with Patrick. Having the docs under version control and a part
> of the release is preferred.
>
> Tom
>
> On Tue, Jul 19, 2011 at 2:54 PM, Patrick Hunt <ph...@apache.org> wrote:
>> I'd advise against this. Only people with filed CLAs can be allowed to
>> commit to your docs, also the PPMC must review each change - currently
>> they are in svn, if you move them to wiki you'll have to manage this
>> issue via wiki auth. See this discussion on whirr:
>> https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503
>>
>> Whirr eventually went with mvn site generation using confluence
>> markup, however I'd probably go with CMS and textile markup at this
>> point (that's what we recently/currently do in ZK)
>> http://www.apache.org/dev/cms.html Additional benefit is that you can
>> use this for both your web site and your docs.
>>
>> Patrick
>>
>> On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <jo...@cloudera.com> wrote:
>>> Hey all,
>>>
>>> I wanted to propose that we port the current documentation from its current
>>> asciidoc form to the wiki. The documentation hasn't had a major structural
>>> update for a while and from some of the lessons we've learned in the past
>>> year it could use a refresh.
>>>
>>> Here are the main trade offs that I currently have with this move.
>>>
>>> Pro:
>>> * Documentation will be easier for more people to modify and update.
>>> * The move would simplify the build -- removing dependencies on several
>>> packages including asciidoc, graphviz, syntax-highilght, and suffers from
>>> version incompatiblity issues across different linux/windows/mac os's.
>>> * By requiring design docs for major new features in the wiki, adding them
>>> to the docs will require less effort.
>>>
>>> Con:
>>> * It will be more difficult to force code commits to make documentation
>>> updates.
>>> * Versioning documentation may become more of a hassle.
>>>
>>> Lets discuss and when it peters out we can vote.
>>>
>>> Thanks,
>>> Jon.
>>>
>>> --
>>> // Jonathan Hsieh (shay)
>>> // Software Engineer, Cloudera
>>> // jon@cloudera.com
>>>
>>
Re: [DISCUSS] Moving docs to Wiki.
Posted by NerdyNick <ne...@gmail.com>.
I agree that the FAQs and Cookbook would be great to add to the wiki.
This would allow those that aren't commiters to contribute back with
there recipes, and would allow for a much faster way of getting FAQs
that come up in the mailing list, up on to the web.
The Dev Guid and User Guide I can see staying in the repo as they
don't really change outside of the releases, and does allow for forced
updating of the docs before a change is committed.
On Thu, Jul 21, 2011 at 7:10 AM, Jonathan Hsieh <jo...@cloudera.com> wrote:
> Would amending the proposal to keep the core formal documentation in the
> repo but to extract some of the transient and operational portions of the
> docs to some sort of CMS (wiki?) be reasonable?
>
> I still think there is a need to make some documentation easier to modify by
> users -- especially the operational and troubleshooting related topics
> (which can be used to when duplicate mailing list questions appear). I'm
> thinking specifically about:
> * the FAQ (which is currently in wiki),
> https://cwiki.apache.org/confluence/display/FLUME/Troubleshooting+FAQ
> * the Cookbook recipes http://archive.cloudera.com/cdh/3/flume/Cookbook/ (old
> link)
> * the Developer guide
> http://archive.cloudera.com/cdh/3/flume/DeveloperGuide/ (old link)
>
> I'm started I've started trying to put questions answer on the mailing list
> into the FAQ -- please do this as you feel like you've encountered a
> question multiple times or believe the question will be asked multiple
> times!
>
> Jon.
>
> On Tue, Jul 19, 2011 at 3:04 PM, Tom White <to...@gmail.com> wrote:
>
>> I agree with Patrick. Having the docs under version control and a part
>> of the release is preferred.
>>
>> Tom
>>
>> On Tue, Jul 19, 2011 at 2:54 PM, Patrick Hunt <ph...@apache.org> wrote:
>> > I'd advise against this. Only people with filed CLAs can be allowed to
>> > commit to your docs, also the PPMC must review each change - currently
>> > they are in svn, if you move them to wiki you'll have to manage this
>> > issue via wiki auth. See this discussion on whirr:
>> >
>> https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503
>> >
>> > Whirr eventually went with mvn site generation using confluence
>> > markup, however I'd probably go with CMS and textile markup at this
>> > point (that's what we recently/currently do in ZK)
>> > http://www.apache.org/dev/cms.html Additional benefit is that you can
>> > use this for both your web site and your docs.
>> >
>> > Patrick
>> >
>> > On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <jo...@cloudera.com>
>> wrote:
>> >> Hey all,
>> >>
>> >> I wanted to propose that we port the current documentation from its
>> current
>> >> asciidoc form to the wiki. The documentation hasn't had a major
>> structural
>> >> update for a while and from some of the lessons we've learned in the
>> past
>> >> year it could use a refresh.
>> >>
>> >> Here are the main trade offs that I currently have with this move.
>> >>
>> >> Pro:
>> >> * Documentation will be easier for more people to modify and update.
>> >> * The move would simplify the build -- removing dependencies on several
>> >> packages including asciidoc, graphviz, syntax-highilght, and suffers
>> from
>> >> version incompatiblity issues across different linux/windows/mac os's.
>> >> * By requiring design docs for major new features in the wiki, adding
>> them
>> >> to the docs will require less effort.
>> >>
>> >> Con:
>> >> * It will be more difficult to force code commits to make documentation
>> >> updates.
>> >> * Versioning documentation may become more of a hassle.
>> >>
>> >> Lets discuss and when it peters out we can vote.
>> >>
>> >> Thanks,
>> >> Jon.
>> >>
>> >> --
>> >> // Jonathan Hsieh (shay)
>> >> // Software Engineer, Cloudera
>> >> // jon@cloudera.com
>> >>
>> >
>>
>
>
>
> --
> // Jonathan Hsieh (shay)
> // Software Engineer, Cloudera
> // jon@cloudera.com
>
--
Nick Verbeck - NerdyNick
----------------------------------------------------
NerdyNick.com
Coloco.ubuntu-rocks.org
Re: [DISCUSS] Moving docs to Wiki.
Posted by Jonathan Hsieh <jo...@cloudera.com>.
Would amending the proposal to keep the core formal documentation in the
repo but to extract some of the transient and operational portions of the
docs to some sort of CMS (wiki?) be reasonable?
I still think there is a need to make some documentation easier to modify by
users -- especially the operational and troubleshooting related topics
(which can be used to when duplicate mailing list questions appear). I'm
thinking specifically about:
* the FAQ (which is currently in wiki),
https://cwiki.apache.org/confluence/display/FLUME/Troubleshooting+FAQ
* the Cookbook recipes http://archive.cloudera.com/cdh/3/flume/Cookbook/ (old
link)
* the Developer guide
http://archive.cloudera.com/cdh/3/flume/DeveloperGuide/ (old link)
I'm started I've started trying to put questions answer on the mailing list
into the FAQ -- please do this as you feel like you've encountered a
question multiple times or believe the question will be asked multiple
times!
Jon.
On Tue, Jul 19, 2011 at 3:04 PM, Tom White <to...@gmail.com> wrote:
> I agree with Patrick. Having the docs under version control and a part
> of the release is preferred.
>
> Tom
>
> On Tue, Jul 19, 2011 at 2:54 PM, Patrick Hunt <ph...@apache.org> wrote:
> > I'd advise against this. Only people with filed CLAs can be allowed to
> > commit to your docs, also the PPMC must review each change - currently
> > they are in svn, if you move them to wiki you'll have to manage this
> > issue via wiki auth. See this discussion on whirr:
> >
> https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503
> >
> > Whirr eventually went with mvn site generation using confluence
> > markup, however I'd probably go with CMS and textile markup at this
> > point (that's what we recently/currently do in ZK)
> > http://www.apache.org/dev/cms.html Additional benefit is that you can
> > use this for both your web site and your docs.
> >
> > Patrick
> >
> > On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <jo...@cloudera.com>
> wrote:
> >> Hey all,
> >>
> >> I wanted to propose that we port the current documentation from its
> current
> >> asciidoc form to the wiki. The documentation hasn't had a major
> structural
> >> update for a while and from some of the lessons we've learned in the
> past
> >> year it could use a refresh.
> >>
> >> Here are the main trade offs that I currently have with this move.
> >>
> >> Pro:
> >> * Documentation will be easier for more people to modify and update.
> >> * The move would simplify the build -- removing dependencies on several
> >> packages including asciidoc, graphviz, syntax-highilght, and suffers
> from
> >> version incompatiblity issues across different linux/windows/mac os's.
> >> * By requiring design docs for major new features in the wiki, adding
> them
> >> to the docs will require less effort.
> >>
> >> Con:
> >> * It will be more difficult to force code commits to make documentation
> >> updates.
> >> * Versioning documentation may become more of a hassle.
> >>
> >> Lets discuss and when it peters out we can vote.
> >>
> >> Thanks,
> >> Jon.
> >>
> >> --
> >> // Jonathan Hsieh (shay)
> >> // Software Engineer, Cloudera
> >> // jon@cloudera.com
> >>
> >
>
--
// Jonathan Hsieh (shay)
// Software Engineer, Cloudera
// jon@cloudera.com
Re: [DISCUSS] Moving docs to Wiki.
Posted by Tom White <to...@gmail.com>.
I agree with Patrick. Having the docs under version control and a part
of the release is preferred.
Tom
On Tue, Jul 19, 2011 at 2:54 PM, Patrick Hunt <ph...@apache.org> wrote:
> I'd advise against this. Only people with filed CLAs can be allowed to
> commit to your docs, also the PPMC must review each change - currently
> they are in svn, if you move them to wiki you'll have to manage this
> issue via wiki auth. See this discussion on whirr:
> https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503
>
> Whirr eventually went with mvn site generation using confluence
> markup, however I'd probably go with CMS and textile markup at this
> point (that's what we recently/currently do in ZK)
> http://www.apache.org/dev/cms.html Additional benefit is that you can
> use this for both your web site and your docs.
>
> Patrick
>
> On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <jo...@cloudera.com> wrote:
>> Hey all,
>>
>> I wanted to propose that we port the current documentation from its current
>> asciidoc form to the wiki. The documentation hasn't had a major structural
>> update for a while and from some of the lessons we've learned in the past
>> year it could use a refresh.
>>
>> Here are the main trade offs that I currently have with this move.
>>
>> Pro:
>> * Documentation will be easier for more people to modify and update.
>> * The move would simplify the build -- removing dependencies on several
>> packages including asciidoc, graphviz, syntax-highilght, and suffers from
>> version incompatiblity issues across different linux/windows/mac os's.
>> * By requiring design docs for major new features in the wiki, adding them
>> to the docs will require less effort.
>>
>> Con:
>> * It will be more difficult to force code commits to make documentation
>> updates.
>> * Versioning documentation may become more of a hassle.
>>
>> Lets discuss and when it peters out we can vote.
>>
>> Thanks,
>> Jon.
>>
>> --
>> // Jonathan Hsieh (shay)
>> // Software Engineer, Cloudera
>> // jon@cloudera.com
>>
>
Re: [DISCUSS] Moving docs to Wiki.
Posted by Patrick Hunt <ph...@apache.org>.
I'd advise against this. Only people with filed CLAs can be allowed to
commit to your docs, also the PPMC must review each change - currently
they are in svn, if you move them to wiki you'll have to manage this
issue via wiki auth. See this discussion on whirr:
https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503
Whirr eventually went with mvn site generation using confluence
markup, however I'd probably go with CMS and textile markup at this
point (that's what we recently/currently do in ZK)
http://www.apache.org/dev/cms.html Additional benefit is that you can
use this for both your web site and your docs.
Patrick
On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <jo...@cloudera.com> wrote:
> Hey all,
>
> I wanted to propose that we port the current documentation from its current
> asciidoc form to the wiki. The documentation hasn't had a major structural
> update for a while and from some of the lessons we've learned in the past
> year it could use a refresh.
>
> Here are the main trade offs that I currently have with this move.
>
> Pro:
> * Documentation will be easier for more people to modify and update.
> * The move would simplify the build -- removing dependencies on several
> packages including asciidoc, graphviz, syntax-highilght, and suffers from
> version incompatiblity issues across different linux/windows/mac os's.
> * By requiring design docs for major new features in the wiki, adding them
> to the docs will require less effort.
>
> Con:
> * It will be more difficult to force code commits to make documentation
> updates.
> * Versioning documentation may become more of a hassle.
>
> Lets discuss and when it peters out we can vote.
>
> Thanks,
> Jon.
>
> --
> // Jonathan Hsieh (shay)
> // Software Engineer, Cloudera
> // jon@cloudera.com
>