Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Hi everybody, Sorry for the delay in replying to this, a combination of illness and work. Here is what is a rough outline of what I propose that solves many of the current problems. This is a proposal and I am happy to amend, discard or accept it based on your comments. My company hired a top documentation writer (MC Brown of MySQL fame, who is unavailable this week, but he'll pick up this thread eventually :) last year and he's been working on our documentation ever since. Of course, since we are distributing a version of Apache CouchDB, the bulk of the documentation overlaps with what is applicable to Apache CouchDB. Right, and for those who have not already seen it we publish that here: http://docs.couchbase.org/couchbase-api/index.html In addition to producing the raw documentation, he also developed a documentations system derived and improved from his experiences with the MySQL documentation system. It is based on DocBook and you can find it on GitHub (https://github.com/CouchOne/CouchDocs produced HTML is in the gh-pages branch (ignore the last-modified date for a second)). This is a slightly older version of the main code, but it's close enough to the current functionality to be useful. We'd be happy to both donate the documentation system and contents to Apache CouchDB as well as have MC spend some of his time working on the official documentation (as well as improving the build system) as any improvements would be mutually beneficial. The documentation system can be managed in version control and understands the notion of releases (I'll leave it to MC to explain the details, if that is needed). Quick version: the backend of the API reference is a metadocs systems that collects the core API details (arguments, HTTP response codes, etc) and then outputs them in a standardised format, both as a summary of the main API calls and the more detailed individual call information, as seen in the current docs. In addition, each item is individually tracked against a version number (including introduced, deprecated and removed versions). This means that you can generate a version of the manual it will output only the information specific to the specified version. In addition, individual sections of the docs can be switched on/off based on the version information. There's more to it than that, but it solves one of the bigger problems of evolving products and versions. The documentation system itself does not yet solve the problem of a low barrier of entry, but there are a few ways to achieve that. My favourite example of this is the PHP documentation where there main docs are in DocBook (surprise) and each rendered HTML page has a comments section open to anyone (including spam, alas, but that seems to be not a big issue). The PHP documentation team has the capabilities to take a comment and make it a bug report with a single click. Once the ticket is closed, the comment disappears, or is marked as integrated. I find that rather neat. Alternatively, we can start manually by embedding a Discuss on every page that we maintain manually until we have a more integrated solution, small steps and all. I don't think requiring users to sign up for JIRA to report a docs issue is a good idea. Right, and just to add the perspective of the MySQL process, the comments at the end of all online documentation pages could contain corrections and updates, and we would update the docs with that information as the comments came in (much like the PHP solution). This makes it easy to collect multiple comments and feeds from different people, while ensuring the docs can be updated. MC -- MC Brown, VP of Documentation m...@couchbase.com Skype: mcmcslp Mobile: +44 7411 295711 (GMT)
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Wow. Went to go and revert the most recent spam. And I found this, check this out: http://wiki.apache.org/couchdb/CouchDB_in_the_wild?action=diffrev1=124rev2=125 This idiot wentforgold person reverted my spam fix, with the comment: Revert to revision 122. The gall!
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Hooray what a great thread :) I was on the cusp of starting one like it myself, although for different reasons. Turns out the the details are all the same. First, the wiki. While it works most of the time and includes most important information it is neither a pleasure to look at nor to work with. It is great that it is a low barrier of entry for contributions, which is a property that we should keep for any potentially other documentation system. In addition, the wiki has many other issues that are system inherent, like the inability to link a code version with a docs version e.g. Here is what is a rough outline of what I propose that solves many of the current problems. This is a proposal and I am happy to amend, discard or accept it based on your comments. My company hired a top documentation writer (MC Brown of MySQL fame, who is unavailable this week, but he'll pick up this thread eventually :) last year and he's been working on our documentation ever since. Of course, since we are distributing a version of Apache CouchDB, the bulk of the documentation overlaps with what is applicable to Apache CouchDB. In addition to producing the raw documentation, he also developed a documentations system derived and improved from his experiences with the MySQL documentation system. It is based on DocBook and you can find it on GitHub (https://github.com/CouchOne/CouchDocs produced HTML is in the gh-pages branch (ignore the last-modified date for a second)). We'd be happy to both donate the documentation system and contents to Apache CouchDB as well as have MC spend some of his time working on the official documentation (as well as improving the build system) as any improvements would be mutually beneficial. The documentation system can be managed in version control and understands the notion of releases (I'll leave it to MC to explain the details, if that is needed). The documentation system itself does not yet solve the problem of a low barrier of entry, but there are a few ways to achieve that. My favourite example of this is the PHP documentation where there main docs are in DocBook (surprise) and each rendered HTML page has a comments section open to anyone (including spam, alas, but that seems to be not a big issue). The PHP documentation team has the capabilities to take a comment and make it a bug report with a single click. Once the ticket is closed, the comment disappears, or is marked as integrated. I find that rather neat. Alternatively, we can start manually by embedding a Discuss on every page that we maintain manually until we have a more integrated solution, small steps and all. I don't think requiring users to sign up for JIRA to report a docs issue is a good idea. To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. Of course, interaction is required, especially when developers forget (hehe) to document new features, but I think this is a good time to open up the project to more contributors for different areas. Note that I am not trying to push something my company has done, I'm just proposing a potential solution to the problem of sub-par docs for Apache CouchDB with the strong desire to get this fixed. I hope you like the proposal, but I'm eager to hear your comments. What do you think? Cheers Jan -- On 13 Jun 2011, at 11:23, Noah Slater wrote: I wish we could do something about the spam. I don't like playing whackamole.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 14:37, Jan Lehnardt wrote: To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. I wouldn't mind getting stuck in with a doc team effort.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 14:37, Jan Lehnardt wrote: https://github.com/CouchOne/CouchDocs 404
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Jan, That's a very kind offer and I think we should pursue it as a team. Are you able to clear all the IP issues? B. On 14 June 2011 14:41, Noah Slater nsla...@apache.org wrote: On 14 Jun 2011, at 14:37, Jan Lehnardt wrote: To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. I wouldn't mind getting stuck in with a doc team effort.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 15:43, Noah Slater wrote: On 14 Jun 2011, at 14:37, Jan Lehnardt wrote: https://github.com/CouchOne/CouchDocs 404 Oh blast it is a private repo, sorry. I was under the impression it is open. I'll check back with the team and report back when there's things to show. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 15:46, Robert Newson wrote: Jan, That's a very kind offer and I think we should pursue it as a team. Are you able to clear all the IP issues? Can you point to specific ones? The way we set things up our side was to make this contribution with as little friction as possible. I.e. the build system code is under the Apache 2.0 license and the docs are under Creative Commons BY-NC-SA 3.0, but we can adopt that as needed. Cheers Jan -- B. On 14 June 2011 14:41, Noah Slater nsla...@apache.org wrote: On 14 Jun 2011, at 14:37, Jan Lehnardt wrote: To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. I wouldn't mind getting stuck in with a doc team effort.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 6:37 AM, Jan Lehnardt j...@apache.org wrote: Hooray what a great thread :) I was on the cusp of starting one like it myself, although for different reasons. Turns out the the details are all the same. First, the wiki. While it works most of the time and includes most important information it is neither a pleasure to look at nor to work with. It is great that it is a low barrier of entry for contributions, which is a property that we should keep for any potentially other documentation system. In addition, the wiki has many other issues that are system inherent, like the inability to link a code version with a docs version e.g. Here is what is a rough outline of what I propose that solves many of the current problems. This is a proposal and I am happy to amend, discard or accept it based on your comments. My company hired a top documentation writer (MC Brown of MySQL fame, who is unavailable this week, but he'll pick up this thread eventually :) last year and he's been working on our documentation ever since. Of course, since we are distributing a version of Apache CouchDB, the bulk of the documentation overlaps with what is applicable to Apache CouchDB. In addition to producing the raw documentation, he also developed a documentations system derived and improved from his experiences with the MySQL documentation system. It is based on DocBook and you can find it on GitHub (https://github.com/CouchOne/CouchDocs produced HTML is in the gh-pages branch (ignore the last-modified date for a second)). We'd be happy to both donate the documentation system and contents to Apache CouchDB as well as have MC spend some of his time working on the official documentation (as well as improving the build system) as any improvements would be mutually beneficial. The documentation system can be managed in version control and understands the notion of releases (I'll leave it to MC to explain the details, if that is needed). The documentation system itself does not yet solve the problem of a low barrier of entry, but there are a few ways to achieve that. My favourite example of this is the PHP documentation where there main docs are in DocBook (surprise) and each rendered HTML page has a comments section open to anyone (including spam, alas, but that seems to be not a big issue). The PHP documentation team has the capabilities to take a comment and make it a bug report with a single click. Once the ticket is closed, the comment disappears, or is marked as integrated. I find that rather neat. Alternatively, we can start manually by embedding a Discuss on every page that we maintain manually until we have a more integrated solution, small steps and all. I don't think requiring users to sign up for JIRA to report a docs issue is a good idea. To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. Of course, interaction is required, especially when developers forget (hehe) to document new features, but I think this is a good time to open up the project to more contributors for different areas. Note that I am not trying to push something my company has done, I'm just proposing a potential solution to the problem of sub-par docs for Apache CouchDB with the strong desire to get this fixed. I hope you like the proposal, but I'm eager to hear your comments. What do you think? Cheers Jan -- It would be a great solution indeed. If we can also manage to build doc distributed with the code would be awesome. Also I hink like davisp suggested, that as developer when we add a feature in the code or see one non documented we should have to put it in the documentation like the Django project does. We already have the same kind of obligation with tests so doc shouldn't be a big problem imo. - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 6:53 AM, Jan Lehnardt j...@apache.org wrote: On 14 Jun 2011, at 15:46, Robert Newson wrote: Jan, That's a very kind offer and I think we should pursue it as a team. Are you able to clear all the IP issues? Can you point to specific ones? The way we set things up our side was to make this contribution with as little friction as possible. I.e. the build system code is under the Apache 2.0 license and the docs are under Creative Commons BY-NC-SA 3.0, but we can adopt that as needed. Cheers Jan -- everything about apache 2 would be nice I guess. - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 9:37 AM, Jan Lehnardt j...@apache.org wrote: Hooray what a great thread :) I was on the cusp of starting one like it myself, although for different reasons. Turns out the the details are all the same. First, the wiki. While it works most of the time and includes most important information it is neither a pleasure to look at nor to work with. It is great that it is a low barrier of entry for contributions, which is a property that we should keep for any potentially other documentation system. In addition, the wiki has many other issues that are system inherent, like the inability to link a code version with a docs version e.g. Here is what is a rough outline of what I propose that solves many of the current problems. This is a proposal and I am happy to amend, discard or accept it based on your comments. My company hired a top documentation writer (MC Brown of MySQL fame, who is unavailable this week, but he'll pick up this thread eventually :) last year and he's been working on our documentation ever since. Of course, since we are distributing a version of Apache CouchDB, the bulk of the documentation overlaps with what is applicable to Apache CouchDB. In addition to producing the raw documentation, he also developed a documentations system derived and improved from his experiences with the MySQL documentation system. It is based on DocBook and you can find it on GitHub (https://github.com/CouchOne/CouchDocs produced HTML is in the gh-pages branch (ignore the last-modified date for a second)). We'd be happy to both donate the documentation system and contents to Apache CouchDB as well as have MC spend some of his time working on the official documentation (as well as improving the build system) as any improvements would be mutually beneficial. The documentation system can be managed in version control and understands the notion of releases (I'll leave it to MC to explain the details, if that is needed). The documentation system itself does not yet solve the problem of a low barrier of entry, but there are a few ways to achieve that. My favourite example of this is the PHP documentation where there main docs are in DocBook (surprise) and each rendered HTML page has a comments section open to anyone (including spam, alas, but that seems to be not a big issue). The PHP documentation team has the capabilities to take a comment and make it a bug report with a single click. Once the ticket is closed, the comment disappears, or is marked as integrated. I find that rather neat. Alternatively, we can start manually by embedding a Discuss on every page that we maintain manually until we have a more integrated solution, small steps and all. I don't think requiring users to sign up for JIRA to report a docs issue is a good idea. To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB Documentation team that can tackle the documentation related issues independently from the core developers. Of course, interaction is required, especially when developers forget (hehe) to document new features, but I think this is a good time to open up the project to more contributors for different areas. Note that I am not trying to push something my company has done, I'm just proposing a potential solution to the problem of sub-par docs for Apache CouchDB with the strong desire to get this fixed. I hope you like the proposal, but I'm eager to hear your comments. What do you think? Cheers Jan -- On 13 Jun 2011, at 11:23, Noah Slater wrote: I wish we could do something about the spam. I don't like playing whackamole. If Noah agrees with the doc system then I'm in. I point him out specifically because of the work I know he was responsible for on the O'Reilly book and he had a couple iterations of how to maintain a large amount of text with code and image inserts so AFAICT he's probably in the best position to make a judgement of what'll be awesome or not. Except for the comments. I agree that we need to allow for super easy contributions without a login, but comments are a blight on the internet. Perhaps a mailto link that opens up dev@ or a form that just emails dev@ or maybe a special docs@ list. If we're gonna work on making our docs all pretty, the last thing we should do is give the collective internet-as-five-year-olds group a big marker to draw all over them.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 15:54, Paul Davis wrote: If Noah agrees with the doc system then I'm in. I point him out specifically because of the work I know he was responsible for on the O'Reilly book and he had a couple iterations of how to maintain a large amount of text with code and image inserts so AFAICT he's probably in the best position to make a judgement of what'll be awesome or not. Thanks, Paul. :) If we're going to ship documentation with CouchDB, I have a good idea about how this should look. I've actually done this before on a previous Autotools based project I was developing for the GNU project itself. We would create the following directory structure: /doc /doc/docbook /doc/docbook/root.xml /doc/docbook/ch1.xml /doc/docbook/ch2.xml /doc/docbook/ch3.xml /doc/Makefile.am You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All very straight forward. The generated files would be included as part of the distribution artefact, but would not be included in the repository. This might also be a good opportunity to make that change for our man page. You realise we have a man page, right? It's just that most people don't have the tool needed to generate it, and we don't ship it by default. Which is a bug. This documentation would then be installed locally on each system that CouchDB is installed on (so that Futon can link right through to it) and we should also export it into the /site directory so that it is available via the web for people who are browsing the CouchDB site. Note, I am not sure where we want to draw the line between documentation and tutorial. An API reference with basic examples would make sense for us to ship. CouchDB TDG, on the other hand, is more tutorial based. I am not sure what kind of documentation CouchBase are working on, but I doubt we'd want to move it all to the source tree. Except for the comments. I agree that we need to allow for super easy contributions without a login, but comments are a blight on the internet. Perhaps a mailto link that opens up dev@ or a form that just emails dev@ or maybe a special docs@ list. If we're gonna work on making our docs all pretty, the last thing we should do is give the collective internet-as-five-year-olds group a big marker to draw all over them. A lesson we learnt from the CouchDB book: collecting comments via email sounds sensible, but proves to be burdensome. Inline or in-page comments, or a bug tracker are both much better solutions.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:13, Noah Slater wrote: On 14 Jun 2011, at 15:54, Paul Davis wrote: If Noah agrees with the doc system then I'm in. I point him out specifically because of the work I know he was responsible for on the O'Reilly book and he had a couple iterations of how to maintain a large amount of text with code and image inserts so AFAICT he's probably in the best position to make a judgement of what'll be awesome or not. Thanks, Paul. :) If we're going to ship documentation with CouchDB, I have a good idea about how this should look. I've actually done this before on a previous Autotools based project I was developing for the GNU project itself. We would create the following directory structure: I'd leave this part to MC as he's got this all figured out :) Note, I am not sure where we want to draw the line between documentation and tutorial. An API reference with basic examples would make sense for us to ship. CouchDB TDG, on the other hand, is more tutorial based. I am not sure what kind of documentation CouchBase are working on, but I doubt we'd want to move it all to the source tree. The first start were API docs, but we'll have tutorials and user guides coming up. I don't see why we should not ship something like a getting started guide (and others) along with the API docs if we choose to. Except for the comments. I agree that we need to allow for super easy contributions without a login, but comments are a blight on the internet. Perhaps a mailto link that opens up dev@ or a form that just emails dev@ or maybe a special docs@ list. If we're gonna work on making our docs all pretty, the last thing we should do is give the collective internet-as-five-year-olds group a big marker to draw all over them. A lesson we learnt from the CouchDB book: collecting comments via email sounds sensible, but proves to be burdensome. Inline or in-page comments, or a bug tracker are both much better solutions. I forgot, if we would use git for version controlling the docs, we could use the GitHub infra (forks, comments, pull requests etc.) to sort all this out and then merge back into ASF git what's stable and license vetted. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 17:18, Jan Lehnardt wrote: I'd leave this part to MC as he's got this all figured out :) Okay, sure. I was more thinking about Autotool stuff here. The first start were API docs, but we'll have tutorials and user guides coming up. I don't see why we should not ship something like a getting started guide (and others) along with the API docs if we choose to. I'm not sure how this would work. I would prefer that the docs be authoritatively kept in the Apache repository. Any other solution would essentially mean accepting patches on the docs from a fork of CouchDB. Right?
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:23, Noah Slater wrote: On 14 Jun 2011, at 17:18, Jan Lehnardt wrote: I'd leave this part to MC as he's got this all figured out :) Okay, sure. I was more thinking about Autotool stuff here. Ah, ok. I know he has a Makefile :) The first start were API docs, but we'll have tutorials and user guides coming up. I don't see why we should not ship something like a getting started guide (and others) along with the API docs if we choose to. I'm not sure how this would work. I would prefer that the docs be authoritatively kept in the Apache repository. That is what I propose as well. Any other solution would essentially mean accepting patches on the docs from a fork of CouchDB. Right? That is common practice already and I don't see a problem with this as long all criteria for ASF commits are fulfilled. That said, I'd not keep the docs in the CouchDB source repo, but on the side (like site/) and only pull things together on release-time. I'd also propose to not bother with SVN on this one as long as the technical side of things is taken care of (Paul?). Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 17:29, Jan Lehnardt wrote: That is common practice already and I don't see a problem with this as long all criteria for ASF commits are fulfilled. Okay. That said, I'd not keep the docs in the CouchDB source repo, but on the side (like site/) and only pull things together on release-time. Disagree very strongly. If you don't include the docs within the CouchDB instance directory, then we will have no record of the docs at a point in time. Say, if you wanted to see the docs for CouchDB 1.3, specifically. Secondly, if they're no in the instance directory, then you cannot build them. That means that people doing a source checkout will not be able to build the docs without going to special lengths. And it means that we wont be able to include them in the release artefacts, because you can't be pulling things from outside the source tree. I'd also propose to not bother with SVN on this one as long as the technical side of things is taken care of (Paul?). Not sure what you mean here.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Hi, On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: Inline or in-page comments Are there any (open source, preferably) systems on the web that support this? I've seen'em around but only for proprietary systems, I think.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:39, Noah Slater wrote: On 14 Jun 2011, at 17:29, Jan Lehnardt wrote: That said, I'd not keep the docs in the CouchDB source repo, but on the side (like site/) and only pull things together on release-time. Disagree very strongly. If you don't include the docs within the CouchDB instance directory, then we will have no record of the docs at a point in time. Say, if you wanted to see the docs for CouchDB 1.3, specifically. I don't see how we can't have release branches and tags on the doc repo in the same way we have on src repo. Secondly, if they're no in the instance directory, then you cannot build them. That means that people doing a source checkout will not be able to build the docs without going to special lengths. And it means that we wont be able to include them in the release artefacts, because you can't be pulling things from outside the source tree. I'm happy to cook up a submodule or repo-based solution that abstracts all that away or reduces it to a minimum, one-time hoop. I'd also propose to not bother with SVN on this one as long as the technical side of things is taken care of (Paul?). Not sure what you mean here. ASF is starting to roll out git infrastructure. If we go for a new repo, I'd say we skip SVN provided the foundation for that is solid. Since Paul is championing this on the ASF side, I'd like to hear his take on this. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Just throwing in my 2 cents in this discussion. On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: /doc /doc/docbook /doc/docbook/root.xml /doc/docbook/ch1.xml /doc/docbook/ch2.xml /doc/docbook/ch3.xml /doc/Makefile.am You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All very straight forward. Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. /J
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:45, Jens Rantil wrote: Just throwing in my 2 cents in this discussion. On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: /doc /doc/docbook /doc/docbook/root.xml /doc/docbook/ch1.xml /doc/docbook/ch2.xml /doc/docbook/ch3.xml /doc/Makefile.am You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All very straight forward. Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. They are also not capable of structuring documentation exhaustively. I hate XML as much as the next guy, but MC's doc system is really slick and not as bad once the basic infrastructure is in place (I'll show it soon, promised). Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
+1 for docs in the same place as the code. One of the main reasons is that a single commit adds the feature, the tests that confirm the feature works, and the doc changes that let folks know about it. It's just sane. And -1 on keeping them floating around externally and sucking them in somehow at release time. B. On 14 June 2011 17:48, Jan Lehnardt j...@apache.org wrote: On 14 Jun 2011, at 18:45, Jens Rantil wrote: Just throwing in my 2 cents in this discussion. On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: /doc /doc/docbook /doc/docbook/root.xml /doc/docbook/ch1.xml /doc/docbook/ch2.xml /doc/docbook/ch3.xml /doc/Makefile.am You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All very straight forward. Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. They are also not capable of structuring documentation exhaustively. I hate XML as much as the next guy, but MC's doc system is really slick and not as bad once the basic infrastructure is in place (I'll show it soon, promised). Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Random suggestion, you could try a couch based system: http://substance.io/ Here is an example: http://substance.io/#michael/data-js No connection to the project, just been following it in the user list. Looks nice. I am sure its missing exports to all the various formats, but hey, we are shooting for everything web based, right? :) Ryan On Tue, Jun 14, 2011 at 10:48 AM, Jan Lehnardt j...@apache.org wrote: On 14 Jun 2011, at 18:45, Jens Rantil wrote: Just throwing in my 2 cents in this discussion. On Jun 14, 2011, at 6:13 PM, Noah Slater wrote: /doc /doc/docbook /doc/docbook/root.xml /doc/docbook/ch1.xml /doc/docbook/ch2.xml /doc/docbook/ch3.xml /doc/Makefile.am You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All very straight forward. Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. They are also not capable of structuring documentation exhaustively. I hate XML as much as the next guy, but MC's doc system is really slick and not as bad once the basic infrastructure is in place (I'll show it soon, promised). Cheers Jan -- -- Twitter: @eckoit http://eckoit.com - Keep what you hear. http://opendoorstories.com - Create Experiences
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 17:48, Jan Lehnardt wrote: On 14 Jun 2011, at 18:45, Jens Rantil wrote: Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. They are also not capable of structuring documentation exhaustively. I hate XML as much as the next guy, but MC's doc system is really slick and not as bad once the basic infrastructure is in place (I'll show it soon, promised). Documentation source format is a bike shed. DocBook is the industry standard and I will veto any plain text alternative. I would suggest we use HTML, but it would be nice to be able to convert the documentation into multiple formats as we will be shipping it with CouchDB.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 17:52, Ryan Ramage wrote: Random suggestion, you could try a couch based system: http://substance.io/ Here is an example: http://substance.io/#michael/data-js No connection to the project, just been following it in the user list. Looks nice. I am sure its missing exports to all the various formats, but hey, we are shooting for everything web based, right? :) Thanks for the suggestion. But I am going to nip all this in the bud right from the get go. We could spend 12 months discussing the best way to author the documentation. It would all be wrong. DocBook is the only sensible option. You thought minor features were like bike sheds? Documentation systems are like a supermarket that only sells cans of paint, and bike sheds.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
+1 for DocBook. On 14 June 2011 17:56, Noah Slater nsla...@apache.org wrote: On 14 Jun 2011, at 17:48, Jan Lehnardt wrote: On 14 Jun 2011, at 18:45, Jens Rantil wrote: Is really writing documentation XML the best we can come up with? How about using 'pandoc' (http://johnmacfarlane.net/pandoc/) to write documentation in restructuredText, markdown or textile instead? They are all way easier to read and write for newcomers. They are also not capable of structuring documentation exhaustively. I hate XML as much as the next guy, but MC's doc system is really slick and not as bad once the basic infrastructure is in place (I'll show it soon, promised). Documentation source format is a bike shed. DocBook is the industry standard and I will veto any plain text alternative. I would suggest we use HTML, but it would be nice to be able to convert the documentation into multiple formats as we will be shipping it with CouchDB.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 17:42, Jan Lehnardt wrote: I don't see how we can't have release branches and tags on the doc repo in the same way we have on src repo. We could also split out the main Erlang files into a separate top level directory, and version that, and keep it in sync with the main branches and release tags. And we could do it for Futon too. But doing so would be a complete nightmare, and it serves no practical purpose. Seriously, this is the wrong direction. If we're shipping the docs with the release artefact, then they should be part of the source tree. Just like the main code, Futon, the system infrastructure stuff, the unit tests, and everything else that comprises an official release.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 9:51 AM, Robert Newson rnew...@apache.org wrote: +1 for docs in the same place as the code. One of the main reasons is that a single commit adds the feature, the tests that confirm the feature works, and the doc changes that let folks know about it. It's just sane. And -1 on keeping them floating around externally and sucking them in somehow at release time. B. The same. - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
anyone thought of using edoc? On Jun 14, 2011, at 1:03 PM, Benoit Chesneau wrote: On Tue, Jun 14, 2011 at 9:51 AM, Robert Newson rnew...@apache.org wrote: +1 for docs in the same place as the code. One of the main reasons is that a single commit adds the feature, the tests that confirm the feature works, and the doc changes that let folks know about it. It's just sane. And -1 on keeping them floating around externally and sucking them in somehow at release time. B. The same. - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:02, Benoit Chesneau wrote: +0 docbook +1 REST Seriously, let's not fall into this trap. And let us not be seduced by so called plain text formats. We made this mistake on the book and I'm in no rush to repeat it. I will quote from an email I sent to our O'Reilly editor. On the CouchDB book, we used a combination of AsciiDoc and GNU Make for the build. We all used our own favourite editor, and GNU Emacs, which I was using at the time, had a major mode for AsciiDoc. I am using BBEdit now, and it doesn't pose a problem. However, I would strongly recommend against using AsciiDoc. As with any format that tries to map to some other format - there are some places it makes things simpler, and some places it makes things more complex. The gzip algorithm, for example, compresses most common things, and expands some of the more uncommon things. You should never notice this, because it is designed well. Unfortunately for us, AsciiDoc isn't as good, and the balance between what it makes easier and what it makes harder was unfortunately weighted in the wrong direction. The amount of hacks, and tweaking, and general ballache it caused me was crazy. I ended up wasting far too much time on this. Add to that the cognitive burden of learning and remembering an entirely new and arbitrary syntax. If we do a second version, or if I do a second book, I will be pushing hard to author in HTML. It's a standard, it works, it's simple, and there are tools to convert it into DocBook. Where they don't exist, I will write them. Working with plain text formats is just too much work. There are too many edge cases where the easy syntax becomes a nightmare and you wish you'd just stuck to something that has the benefit of 20 year's collective experience, refinements, and authoring tools available. — November, 2009
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
I'd also propose to not bother with SVN on this one as long as the technical side of things is taken care of (Paul?). Not sure what you mean here. ASF is starting to roll out git infrastructure. If we go for a new repo, I'd say we skip SVN provided the foundation for that is solid. Since Paul is championing this on the ASF side, I'd like to hear his take on this. Cheers Jan -- What's the question here? I plan on doing the whole discuss new VCS after I roll the 1.0.3 release that I started work on last night.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:07, Robert Dionne wrote: anyone thought of using edoc? I think there is a place for automatically generated documentation, but this should probably be discussed separately.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 10:13 AM, Noah Slater nsla...@apache.org wrote: On 14 Jun 2011, at 18:02, Benoit Chesneau wrote: +0 docbook +1 REST Seriously, let's not fall into this trap. And let us not be seduced by so called plain text formats. We made this mistake on the book and I'm in no rush to repeat it. I will quote from an email I sent to our O'Reilly editor. On the CouchDB book, we used a combination of AsciiDoc and GNU Make for the build. We all used our own favourite editor, and GNU Emacs, which I was using at the time, had a major mode for AsciiDoc. I am using BBEdit now, and it doesn't pose a problem. However, I would strongly recommend against using AsciiDoc. As with any format that tries to map to some other format - there are some places it makes things simpler, and some places it makes things more complex. The gzip algorithm, for example, compresses most common things, and expands some of the more uncommon things. You should never notice this, because it is designed well. Unfortunately for us, AsciiDoc isn't as good, and the balance between what it makes easier and what it makes harder was unfortunately weighted in the wrong direction. The amount of hacks, and tweaking, and general ballache it caused me was crazy. I ended up wasting far too much time on this. Add to that the cognitive burden of learning and remembering an entirely new and arbitrary syntax. If we do a second version, or if I do a second book, I will be pushing hard to author in HTML. It's a standard, it works, it's simple, and there are tools to convert it into DocBook. Where they don't exist, I will write them. Working with plain text formats is just too much work. There are too many edge cases where the easy syntax becomes a nightmare and you wish you'd just stuck to something that has the benefit of 20 year's collective experience, refinements, and authoring tools available. — November, 2009 I understand. So is your suggestion to just use docbook or html ? Both are OK for me . - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 18:31, Benoit Chesneau wrote: I understand. So is your suggestion to just use docbook or html ? Both are OK for me . DocBook in this instance. It will make tooling and build time compilation much smoother. And there are plenty of editors for it. HTML would be okay if it was only being done once per edition of a book, where you can afford the one-off cost of converting the HTML to DocBook. But there are no good tools for this at the moment.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 19:02, Noah Slater wrote: On 14 Jun 2011, at 17:42, Jan Lehnardt wrote: I don't see how we can't have release branches and tags on the doc repo in the same way we have on src repo. We could also split out the main Erlang files into a separate top level directory, and version that, and keep it in sync with the main branches and release tags. And we could do it for Futon too. But doing so would be a complete nightmare, and it serves no practical purpose. Seriously, this is the wrong direction. If we're shipping the docs with the release artefact, then they should be part of the source tree. Just like the main code, Futon, the system infrastructure stuff, the unit tests, and everything else that comprises an official release. I'd actually argue that with Futon it'd be a great idea as would be the contrib/ dir and probably others. All the problems you and Robert outline can be solved by proper tooling. Android is using the repo tool, as we do at Couchbase and it does all of the above and makes for a decent experience (please refrain from horror stories about this or other tools in order to keep this thread on track). That said, I will no longer advocate the separate repository option. If we find issues with docs in the source tree down the road, we can still opt for something else. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 19:13, Paul Davis wrote: I'd also propose to not bother with SVN on this one as long as the technical side of things is taken care of (Paul?). Not sure what you mean here. ASF is starting to roll out git infrastructure. If we go for a new repo, I'd say we skip SVN provided the foundation for that is solid. Since Paul is championing this on the ASF side, I'd like to hear his take on this. Cheers Jan -- What's the question here? I plan on doing the whole discuss new VCS after I roll the 1.0.3 release that I started work on last night. This was use git for docs only to get started with this, not the general move discussion. That said, I retract my question as we seem to be going for in-src-repo docs. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
This has thread has probably been the most productive thing wentforgold has ever contributed to the web.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 20:27, Noah Slater wrote: This has thread has probably been the most productive thing wentforgold has ever contributed to the web. What has thread?
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 19:28, Jan Lehnardt wrote: On 14 Jun 2011, at 20:27, Noah Slater wrote: This has thread has probably been the most productive thing wentforgold has ever contributed to the web. What has thread? Typo. :) s,has,,
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 20:48, Noah Slater wrote: On 14 Jun 2011, at 19:28, Jan Lehnardt wrote: On 14 Jun 2011, at 20:27, Noah Slater wrote: This has thread has probably been the most productive thing wentforgold has ever contributed to the web. What has thread? Typo. :) s,has,, Thread has typo then :D
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Tue, Jun 14, 2011 at 19:13, Noah Slater nsla...@apache.org wrote: +0 docbook +1 REST Seriously, let's not fall into this trap. And let us not be seduced by so called plain text formats. We made this mistake on the book and I'm in no rush to repeat it. Sorry to contribute to the bikeshed, but I'm just going to get this off my chest. From your email, this seems like a false generalization, at least, going from AsciiDoc to all plain text formats. I don't know if you've used reStructuredText, but it's seriously flexible and comes with good (easily customizable) latex and html conversion out of the box. I understand DocBook is awesome for print things, but experience has also shown that DocBook has a significantly higher barrier to entry. Going from a wiki to DocBook is like moving to the entire other end of the scale (okay, going with latex would be worse). You had a bad experience with AsciiDoc, but Sphinx is just awesome. Cheers, Dirkjan
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 21:56, Dirkjan Ochtman wrote: On Tue, Jun 14, 2011 at 19:13, Noah Slater nsla...@apache.org wrote: +0 docbook +1 REST Seriously, let's not fall into this trap. And let us not be seduced by so called plain text formats. We made this mistake on the book and I'm in no rush to repeat it. Sorry to contribute to the bikeshed, but I'm just going to get this off my chest. From your email, this seems like a false generalization, at least, going from AsciiDoc to all plain text formats. I don't know if you've used reStructuredText, but it's seriously flexible and comes with good (easily customizable) latex and html conversion out of the box. I understand DocBook is awesome for print things, but experience has also shown that DocBook has a significantly higher barrier to entry. On the lowest level, we will not require any DocBook knowledge. For the folks who want to make awesome docs, we should give them the best tools and I think we found a solution here. Cheers Jan --
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 20:56, Dirkjan Ochtman wrote: From your email, this seems like a false generalization, at least, going from AsciiDoc to all plain text formats. I don't know if you've used reStructuredText, but it's seriously flexible and comes with good (easily customizable) latex and html conversion out of the box. I understand DocBook is awesome for print things, but experience has also shown that DocBook has a significantly higher barrier to entry. Going from a wiki to DocBook is like moving to the entire other end of the scale (okay, going with latex would be worse). You had a bad experience with AsciiDoc, but Sphinx is just awesome. What you saw there is the tip of the iceberg. It just so happens that I am sharing my experience with AsciiDoc, but my complaints stem from experience with a whole bunch of plain text syntaxes. At the root of it, DocBook is a plain text syntax. I don't know why people think XML or HTML are somehow binary or something. I mean, seriously. It's just text. DocBook isn't hard to author in If you don't like typing tags, then you wont like typing markup in any language. What DocBook (or HTML) has over something like REST or Markdown or any of this other shovelware, is that its syntax is known by more people, more intuitively, and comes with more authoring tools. If you hand me a DocBook file, I can hand you back a man page, an info page, a HTML site, a PDF, and some PostScript within about 5 minutes. Give me another half an hour, and I've baked it into the build system. Also, rainbows and ponies. Seriously. Ubiquity is severely underrated.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 14 Jun 2011, at 21:05, Jan Lehnardt wrote: On the lowest level, we will not require any DocBook knowledge. For the folks who want to make awesome docs, we should give them the best tools and I think we found a solution here. Agreed. If someone sends us a a great text file with tons of useful stuff in it but no formatting whatsoever, I will happily turn that into DocBook for them.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 15 June 2011 08:25, Noah Slater nsla...@apache.org wrote: On 14 Jun 2011, at 21:05, Jan Lehnardt wrote: On the lowest level, we will not require any DocBook knowledge. For the folks who want to make awesome docs, we should give them the best tools and I think we found a solution here. Agreed. If someone sends us a a great text file with tons of useful stuff in it but no formatting whatsoever, I will happily turn that into DocBook for them. +1 to this thread; improving docs was on my list of Things We Should Have Sorted at CouchCamp. In summary are we saying: * leveraging CouchBase's stuff staff * commit requires documentation * releases to include full API doc * use a strong backend i.e. docbook * have a frontend that enables simple contribution/commenting (the Definitive Guide is perfect for me - issues go to a ticketing system) * providing a clear visible lower barrier of entry than XML (even if it means us reformatting contributions) I think we'd need to cover: * build solid core docs first incl APIs solid examples * sort out http://couchdb.apache.org/ as well (thought davisp would have mentioned this already) * update the Definitive Guide especially the example couchapp sofa which is super out of date I have a few personal things to do in next 3 months, but after that put some real long-term effort into this. Finally, it would be cool if CouchDB came with an embedded docs.couch - maybe even as a CouchApp, and updated itself by replicating. But thats a poor second to having good documentation in the first place. One step at a time. A+ Dave
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
I wish we could do something about the spam. I don't like playing whackamole.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 5:23 AM, Noah Slater nsla...@apache.org wrote: I wish we could do something about the spam. I don't like playing whackamole. We could delete the wiki and create real docs.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 5:34 AM, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 5:23 AM, Noah Slater nsla...@apache.org wrote: I wish we could do something about the spam. I don't like playing whackamole. We could delete the wiki and create real docs. +1 . something available on the versioning. Maybe right after the git call ? - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
What percentage of useful wiki edits were made by committers vs non-committers? On 13 Jun 2011, at 13:41, Benoit Chesneau wrote: On Mon, Jun 13, 2011 at 5:34 AM, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 5:23 AM, Noah Slater nsla...@apache.org wrote: I wish we could do something about the spam. I don't like playing whackamole. We could delete the wiki and create real docs. +1 . something available on the versioning. Maybe right after the git call ? - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
+1 to deleting the wiki and +1 to real docs. B. On 13 June 2011 13:49, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? On 13 Jun 2011, at 13:41, Benoit Chesneau wrote: On Mon, Jun 13, 2011 at 5:34 AM, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 5:23 AM, Noah Slater nsla...@apache.org wrote: I wish we could do something about the spam. I don't like playing whackamole. We could delete the wiki and create real docs. +1 . something available on the versioning. Maybe right after the git call ? - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 5:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? We could have edit from users too or just mails on non wiki systems. For example on gunicorn, The users open a ticket with a correction. Or maybe we could have a wiki also available on the revision system. The good point of having static doc is that we could distribute it with the sources, so I don't rely on any connections to read them or whatever. - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 8:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? http://en.wikipedia.org/wiki/Toilet_paper_orientation On 13 Jun 2011, at 13:41, Benoit Chesneau wrote: On Mon, Jun 13, 2011 at 5:34 AM, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 5:23 AM, Noah Slater nsla...@apache.org wrote: I wish we could do something about the spam. I don't like playing whackamole. We could delete the wiki and create real docs. +1 . something available on the versioning. Maybe right after the git call ? - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 13 Jun 2011, at 13:55, Paul Davis wrote: On Mon, Jun 13, 2011 at 8:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? http://en.wikipedia.org/wiki/Toilet_paper_orientation Not sure how this is relevant. If we decommission the wiki we are putting up barriers to contribution from non-committers. So it is arguably worth while understanding exactly what that means for us. How many people have contributed in the past who could not have contributed if this had been the case?
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Jun 13, 2011, at 9:13 AM, Noah Slater wrote: On 13 Jun 2011, at 13:55, Paul Davis wrote: On Mon, Jun 13, 2011 at 8:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? http://en.wikipedia.org/wiki/Toilet_paper_orientation Not sure how this is relevant. If we decommission the wiki we are putting up barriers to contribution from non-committers. So it is arguably worth while understanding exactly what that means for us. How many people have contributed in the past who could not have contributed if this had been the case? I think the WIKI is useful. The APi docs are pretty good, everything is there, though it takes a while to get used to how to find it all.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 6:18 AM, Robert Dionne dio...@dionne-associates.com wrote: On Jun 13, 2011, at 9:13 AM, Noah Slater wrote: On 13 Jun 2011, at 13:55, Paul Davis wrote: On Mon, Jun 13, 2011 at 8:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? http://en.wikipedia.org/wiki/Toilet_paper_orientation Not sure how this is relevant. If we decommission the wiki we are putting up barriers to contribution from non-committers. So it is arguably worth while understanding exactly what that means for us. How many people have contributed in the past who could not have contributed if this had been the case? I think the WIKI is useful. The APi docs are pretty good, everything is there, though it takes a while to get used to how to find it all. useful for sure, but it can't be put in in the archive doc folder though. (I know... we don't have even a doc folder in the archive...) - benoît
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 9:13 AM, Noah Slater nsla...@apache.org wrote: On 13 Jun 2011, at 13:55, Paul Davis wrote: On Mon, Jun 13, 2011 at 8:49 AM, Noah Slater nsla...@apache.org wrote: What percentage of useful wiki edits were made by committers vs non-committers? http://en.wikipedia.org/wiki/Toilet_paper_orientation Not sure how this is relevant. If we decommission the wiki we are putting up barriers to contribution from non-committers. So it is arguably worth while understanding exactly what that means for us. How many people have contributed in the past who could not have contributed if this had been the case? The mode of contribution changes. There is nothing that will suddenly prevent people from contributing. Its just that making a contribution becomes a JIRA issue instead of a wiki update. Under that light your question becomes, How many people contributed to the wiki that couldn't manage to fill out a JIRA issue? The only way to truly understand what it'd be like to use the new system would be to build it and start using it in preference to the wiki. If it dies a gruesome death, then the wiki won. If not then eventually we'll say Oh look, the wiki still sucks and we have all of this glorious, glorious documentation. How fabulous! And then we will drink tea from small cups on saucers with an appropriately extended pinky finger and a monocle. http://en.wikipedia.org/wiki/Talk:Barack_Obama#Mention_of_conspiracy_theories_in_the_article.3F
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 15:31, Paul Davis paul.joseph.da...@gmail.com wrote: The mode of contribution changes. There is nothing that will suddenly prevent people from contributing. Its just that making a contribution becomes a JIRA issue instead of a wiki update. Under that light your question becomes, How many people contributed to the wiki that couldn't manage to fill out a JIRA issue? Wouldn't or couldn't? Cheers, Dirkjan
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
How many people didn't edit the wiki because it's a scary prospect to edit the only form of documentation that there seems to be? +1 to pinky fingers and monocles Thanks Clare On 13/06/11 15:15, Dirkjan Ochtman wrote: On Mon, Jun 13, 2011 at 15:31, Paul Davispaul.joseph.da...@gmail.com wrote: The mode of contribution changes. There is nothing that will suddenly prevent people from contributing. Its just that making a contribution becomes a JIRA issue instead of a wiki update. Under that light your question becomes, How many people contributed to the wiki that couldn't manage to fill out a JIRA issue? Wouldn't or couldn't? Cheers, Dirkjan
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 13 Jun 2011, at 18:16, Peter Nolan wrote: What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) Because we nuke it as it arrives. That's what prompted my original email. But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. I am one, and I'm sick of doing it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. They are. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. Not gonna happen. It's MoinMoin or Confluence. :)
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On 13 Jun 2011, at 19:08, Paul Davis wrote: You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. Paul is right on the money here. The release team already has enough work to do without rounding up documentation. ;)
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
++1 On Jun 13, 2011, at 2:05 PM, Robert Newson wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
++1++ On Jun 13, 2011, at 2:08 PM, Paul Davis wrote: On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
+1 for commit requirement in addition to being a release requirement. At the very least, we get the docs fixed during the release process, but it ought to be done with the commit itself. In practice, we'll forget sometimes, and then be reminded by others on the team. B. On 13 June 2011 19:17, Robert Dionne dio...@dionne-associates.com wrote: ++1++ On Jun 13, 2011, at 2:08 PM, Paul Davis wrote: On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Didn't couch/couchone/couchbase/whateveritscalledthisweek hire a writer? If you need a writer for documentation I'm more than willing to contribute. Eye dun rite gud.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
On Mon, Jun 13, 2011 at 2:27 PM, Robert Newson robert.new...@gmail.com wrote: +1 for commit requirement in addition to being a release requirement. At the very least, we get the docs fixed during the release process, but it ought to be done with the commit itself. In practice, we'll forget sometimes, and then be reminded by others on the team. Right. I'm saying reminded by others should be commit vetoed. B. On 13 June 2011 19:17, Robert Dionne dio...@dionne-associates.com wrote: ++1++ On Jun 13, 2011, at 2:08 PM, Paul Davis wrote: On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Also we should jab them with forks. On 13 June 2011 19:28, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 2:27 PM, Robert Newson robert.new...@gmail.com wrote: +1 for commit requirement in addition to being a release requirement. At the very least, we get the docs fixed during the release process, but it ought to be done with the commit itself. In practice, we'll forget sometimes, and then be reminded by others on the team. Right. I'm saying reminded by others should be commit vetoed. B. On 13 June 2011 19:17, Robert Dionne dio...@dionne-associates.com wrote: ++1++ On Jun 13, 2011, at 2:08 PM, Paul Davis wrote: On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
Yes, Peter, there is better documentation available for couchdb outside of our the projects official site. That's part of the problem we're addressing. The best place for couchdb documentation should be couchdb.apache.org, like it is for most other Apache projects. B. On 13 June 2011 19:30, Robert Newson robert.new...@gmail.com wrote: Also we should jab them with forks. On 13 June 2011 19:28, Paul Davis paul.joseph.da...@gmail.com wrote: On Mon, Jun 13, 2011 at 2:27 PM, Robert Newson robert.new...@gmail.com wrote: +1 for commit requirement in addition to being a release requirement. At the very least, we get the docs fixed during the release process, but it ought to be done with the commit itself. In practice, we'll forget sometimes, and then be reminded by others on the team. Right. I'm saying reminded by others should be commit vetoed. B. On 13 June 2011 19:17, Robert Dionne dio...@dionne-associates.com wrote: ++1++ On Jun 13, 2011, at 2:08 PM, Paul Davis wrote: On Mon, Jun 13, 2011 at 2:05 PM, Robert Newson robert.new...@gmail.com wrote: It's not the wiki per se that bothers me, it's that it's the primary, often only, source of documentation. I propose that future releases of CouchDB include at least a full description of all public API's. Improvements above that base level would be a manual and/or simple tutorials. This documentation would be maintained in the same source tree as the code and it would be a release requirement for this documentation to be updated to include all new features. You had me until you said release requirement. I would upgrade that to commit requirement if we're seriously about having such documentation. If we don't force people to make sure docs reflect changes at commit time then its probably going to be a lost cause. This documentation is then the primary source, the wiki can serve as a supplement. b. On 13 June 2011 18:16, Peter Nolan peterwno...@gmail.com wrote: Any documentation is good. What is this 'spam'? Haven't personally encountered anything on the wiki that would be 'considered' spam (perhaps not stumbled upon that portion?) But it's inevitable that the wiki will be attacked by unscrupulous people and as such, the wiki should prepare for this. The wiki is going to need gatekeepers/admins to maintain it. It would be nice, that any edits be archived so users can see previous states of the page if they so choose so. If a noted jerk keeps editing the wiki, we should have a system that only applies his edits to his account. The common user would not see his edits, only he would, which would hopefully convince him that his edit has gone through. +1 top hats.
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
It doesn't matter where the 'centralized' information is located, it just needs to be centralized. There are a bunch of great little bits of information scattered throughout the internet, from blogs, to stackoverflow etc. Out of curiosity, how hard is it to create plugins for firefox? If one wanted to create a plugin that allowed users to upload urls of useful information to the couchdb wiki, how long would it take them? Assuming they know js, couch, html and css only. That'd be a nice little project to put on the back burner. -Pete
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
I'd argue that it matters a great deal. Our project should include good documentation. B. On 13 June 2011 19:46, Peter Nolan peterwno...@gmail.com wrote: It doesn't matter where the 'centralized' information is located, it just needs to be centralized. There are a bunch of great little bits of information scattered throughout the internet, from blogs, to stackoverflow etc. Out of curiosity, how hard is it to create plugins for firefox? If one wanted to create a plugin that allowed users to upload urls of useful information to the couchdb wiki, how long would it take them? Assuming they know js, couch, html and css only. That'd be a nice little project to put on the back burner. -Pete
Re: [Couchdb Wiki] Trivial Update of CouchDB_in_the_wild by wentforgold
The point that was trying to be made was that a database system that allows such an extreme degree of decentralization (with replication and whatnot) is that information is incredibly decentralized. Having a location that contains all necessary documentation is incredibly important.
