Hi guys, 1. I think we can simply rename all the readme's to .md since some of them are already markdown anyway. I think nobody is against it, right? I was going to do that already in /lib/js, so I can do it for the others too...
2. merging the tutorials to the tests would be quite complicated without losing the points mentioned by Roger, so -1, unless anyone finds a very creative way of doing so :) We need simple and understandable tutorials and high-coverage tests. Perhaps we could simplify the lib readme's by properly linking or including the tutorials. If we could also use the same text on the website, we would only have two reference points: one for a brief introduction and another for the deep automatic tests necessary for a good integration between all target languages. 3. I'm afraid, I'm also against moving the readme's to a central place, since many users tend to only look into one or two specific libraries. Some package systems even only deploy single libraries. We could symlink them to /doc like Nevo said if you think it'd be useful... - Henrique On 7 March 2014 18:11, Roger Meier <ro...@bufferoverflow.ch> wrote: > yes I think we should do so. this was part of the initial post below: > contrib/<topic>/README.md => thrift.apache.org/<topic> > > moving all README.md files to doc folder is similar to having the website > within > the source tree... I would really prefer a filter to map the URL's as > suggested. > > Can we rename all README files to README.md? any concerns? > > have a nice weekend! > -roger > > > Quoting Jens Geyer <jensge...@hotmail.com>: > > Can we (and should we) integrate the contribs somehow? Although not part >> of the core, most of them could really do a good job enhancing our >> documentation by showing the possibilities. Including the two I plan to >> commit today, unless anyone votes against it. >> ________________________________ >> Von: Jens Geyer >> Gesendet: 06.03.2014 21:25 >> An: dev@thrift.apache.org; jfarr...@apache.org; Roger Meier >> Cc: jfarr...@apache.org; dev@thrift.apache.org >> Betreff: Re: source doc to website >> >> On a related note, what does everyone think of removing /test and using >>> /tutorials for cross language testing instead. This could make the >>> tutorials >>> more robust and keep from having duplicate code samples in tests and >>> tutorials. >>> >> >> +1 brilliant, really. >> >> >> -----Ursprüngliche Nachricht----- >> From: Jake Farrell >> Sent: Thursday, March 6, 2014 1:15 AM >> To: Roger Meier >> Cc: jfarr...@apache.org ; dev@thrift.apache.org >> Subject: Re: source doc to website >> >> Hey Roger >> Excellent discussion thread to start, this is one key area we have >> struggled with for awhile. >> >> Thoughts on moving them all into /docs and naming them appropriately? I >> think this would be a better approach and make it easier to link and cross >> reference between the docs and would make it easier to add all of them >> into >> /docs on the website. Having all of the documentation spread across the >> codebase will also make small updates harder and for new users to search >> for information. If everyone is in favor of the README.md files in each >> specific location then we can come up with something to map and filter >> them >> into content for the website. >> >> On a related note, what does everyone think of removing /test and using >> /tutorials for cross language testing instead. This could make the >> tutorials more robust and keep from having duplicate code samples in tests >> and tutorials. >> >> -Jake >> >> >> >> On Wed, Mar 5, 2014 at 4:45 PM, Roger Meier <ro...@bufferoverflow.ch> >> wrote: >> >> Hi Jake & co >>> >>> Do you have any trick to integrate some readme's located within the >>> source >>> tree? >>> >>> Source file: Web Site >>> URL: >>> test/README.md >>> thrift.apache.org/test >>> test/STATUS.md >>> thrift.apache.org/test/status >>> test/keys/README.md thrift.apache.org/test/keys >>> lib/<lang>/README.md thrift.apache.org/lib/ >>> <lang> >>> lib/<lang>/test/README.md thrift.apache.org/lib/<lang>/ >>> test >>> lib/<lang>/examples/README.md thrift.apache.org/lib/<lang>/examples >>> compiler/cpp/README thrift.apache.org/compiler >>> debian/README >>> thrift.apache.org/debian >>> contrib/<topic>/README thrift.apache.org/<topic> >>> >>> Name consistency is another topic... >>> What about renaming all README files to README.md and start use markdown >>> all >>> over? >>> >>> Other stuff to integrate or align in some way: >>> ./tutorial/README >>> ./tutorial/erl/README >>> ./tutorial/java/README >>> ./tutorial/ocaml/README >>> ./README >>> >>> All the best! >>> -roger >>> >>> >>> > >
