You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flume.apache.org by "Ralph Goers (JIRA)" <ji...@apache.org> on 2012/07/30 07:24:33 UTC
[jira] [Created] (FLUME-1406) Remove documentation from flume trunk
Ralph Goers created FLUME-1406:
----------------------------------
Summary: Remove documentation from flume trunk
Key: FLUME-1406
URL: https://issues.apache.org/jira/browse/FLUME-1406
Project: Flume
Issue Type: Bug
Components: Docs
Affects Versions: v1.3.0
Environment: All
Reporter: Ralph Goers
The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Mike Percy (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13425324#comment-13425324 ]
Mike Percy commented on FLUME-1406:
-----------------------------------
I suspect that posting bleeding-edge trunk docs on the site could confuse users as to which version it applies. It also seems that forcing developers to submit two patches for every doc-affecting change disincentivizes them to update the docs. IMO it's better to keep all the docs with the code, and make it a manual release step to copy the generated docs snapshots into the site SVN repo at release time.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13424961#comment-13424961 ]
Ralph Goers commented on FLUME-1406:
------------------------------------
The documentation is now hosted at https://svn.apache.org/repos/asf/flume/site/trunk/content/sphinx/. When you modify the documentation there it causes the web site to be updated, so you can always get the latest documentation there. I don't disagree that developers should update the documentation when they make changes. They just need to do it in a different place.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Juhani Connolly (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13426346#comment-13426346 ]
Juhani Connolly commented on FLUME-1406:
----------------------------------------
Fwiw, just to get input in this I too feel that removing them from the base source is going to be harmful. It is less awkward to be jumping between two different systems, and I think that bleeding edge documents are only useful if we also provide a bleeding edge nightly build on the website, otherwise they're only a cause of confusion as people will try to use settings/components that don't exist in the current release, and I think this is a bigger one than any matter of convenience.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Mike Percy (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13425968#comment-13425968 ]
Mike Percy commented on FLUME-1406:
-----------------------------------
Adding features / config options to existing components is likely between releases too. The documentation is still very sparse. Adding barriers to developer contributions to the docs isn't going to help that.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Patrick Wendell (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13424981#comment-13424981 ]
Patrick Wendell commented on FLUME-1406:
----------------------------------------
Two questions
How would this affect the patch submission process - we just submit a separate diff which is rooted in the /site/ directory?
Also - if some day flume splits into two or more major branches, it seems like there is no way to maintain branched documentation then, right?
- Patrick
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (FLUME-1406) Remove documentation from flume trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Ralph Goers updated FLUME-1406:
-------------------------------
Comment: was deleted
(was: Patch to remove the documentation from flume trunk)
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Jarek Jarcec Cecho (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13424955#comment-13424955 ]
Jarek Jarcec Cecho commented on FLUME-1406:
-------------------------------------------
Why do you think that documentation should be removed from the trunk, Ralph?
The reason why I'm asking is that I personally believe that documentation should be included in the sources. Every patch adding new functionality should also provide update to the documentation (User and Dev guide). So that every time somebody will clone trunk he will get consistent documentation for the sources he just got.
Jarcec
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13424996#comment-13424996 ]
Ralph Goers commented on FLUME-1406:
------------------------------------
Patrick - yes, you would submit a patch from the site directory.
To answer both of you, it is expected that the site will be branched with each release and the whole site should be included in the source distribution.
Users are more important than developers. Users's generally do not want to download the sources and build. Users generally prefer to get the documentation off of the web site. I would suggest you review your own habits. Do you generally download all the projects you are dependent on to get ahold of their documentation or do you want access to the documentation on the project's web site?
I can't quantify this, but I am going to guess that differences in the content of the guides between releases will have more fixes and updates to documentation of existing features then it will documentation of new features. Making these updates available to users on the site quickly is important, especially any new features can simply include the release they will be available in.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (FLUME-1406) Remove documentation from flume trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Ralph Goers updated FLUME-1406:
-------------------------------
Attachment: docPatch.txt
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Patrick Wendell (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13425014#comment-13425014 ]
Patrick Wendell commented on FLUME-1406:
----------------------------------------
I wasn't opining - just inquiring.
So the tradeoff here is that it will gaurentee that the latest docs are always on the website, but it will be clunkier to manage historical per-release docs, since they won't be included directly in the branch source tree.
Patrick
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13425023#comment-13425023 ]
Ralph Goers commented on FLUME-1406:
------------------------------------
Essentially, yes. I had thought about using svn externals but since the code will be moving to git that wouldn't work. The release process should only include a couple of steps beyond what is done now but changes for that would be in a separate patch.
Note that the web site contains the per-release documentation as PDFs.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13426078#comment-13426078 ]
Ralph Goers commented on FLUME-1406:
------------------------------------
What barriers? My experience with other projects is that the faster the doc gets in front of customers the more likely documentation is to be updated, which is the inverse of what you are advocating.
>From the sounds of this it looks like there is an impasse here. It sounds like you are vetoing removing the docs from the build and I would veto their removal from the web site so we are going to be stuck with finding a process that keeps them in synch.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Jarek Jarcec Cecho (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13424984#comment-13424984 ]
Jarek Jarcec Cecho commented on FLUME-1406:
-------------------------------------------
I don't believe that we should have just one documentation on the webpages for the "bleeding edge". I believe that better option would be to have there separate documentation for each version that we've released. My reasoning here is that user should be able to google the right documentation for his version. That's another reason why I do prefer to have the documentation tied to the sources.
Jarcec
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (FLUME-1406) Remove documentation from flume
trunk
Posted by "Ralph Goers (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/FLUME-1406?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13425348#comment-13425348 ]
Ralph Goers commented on FLUME-1406:
------------------------------------
FLUME-1407 is a prime example of why I strongly disagree. Here the user reported a documentation error and it was fixed and live on the web site within a couple of hours. Without that ability users would have to wait for the next release for documentation corrections. Again, fixing documentation errors and enhancing documentation of existing components is likely to far outweigh the amount of documentation that occurs for new features.
> Remove documentation from flume trunk
> -------------------------------------
>
> Key: FLUME-1406
> URL: https://issues.apache.org/jira/browse/FLUME-1406
> Project: Flume
> Issue Type: Bug
> Components: Docs
> Affects Versions: v1.3.0
> Environment: All
> Reporter: Ralph Goers
> Attachments: docPatch.txt
>
>
> The user's and developer's guides are part of the web site and should be removed from flume trunk
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira