Hi Jake
Yes, docs within docs folder is easier to handle for web site generation. However, people will usually search die internet instead of browsing the doc folder. We have this folder since years I think, people like to have a README.md within the current working directory. ==>better visibility and probably the reason why we have lot of README.md files within our code base. Let us continue this direction of evolution! Rename all README to README.md and define Markdown syntax as the way to go? Merge test with tutorial will be a huge task and I see different goals: test: * complex code with lot variants(types, exceptions, protocols, transports, multiplex, ssl, servers, etc.) * the wide range of features is usually not what you need as a starting point for own projects * TestServer and TestServer for all languages use the same command line arguments * ThriftTest.thrift defines all types and describes the behavior of services or initial values of objects, etc. tutorial: * very simple example: a calculator * just use a sub set of Types and a Custom Exception * no extra libraries such as command line parser & co * minimum amount of required code The other idea I had is using the multiplex protocol for this new combination/merge of tutorial and test -Roger From: Jake Farrell [mailto:jfarr...@apache.org] Sent: Donnerstag, 6. März 2014 01:16 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 <mailto: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 <http://thrift.apache.org/testtest/STATUS.md> test/STATUS.md thrift.apache.org/test/status <http://thrift.apache.org/test/status> test/keys/README.md thrift.apache.org/test/keys <http://thrift.apache.org/test/keyslib/> lib/<lang>/README.md thrift.apache.org/lib/ <http://thrift.apache.org/lib/> <lang> lib/<lang>/test/README.md thrift.apache.org/lib/ <http://thrift.apache.org/lib/> <lang>/test lib/<lang>/examples/README.md thrift.apache.org/lib/ <http://thrift.apache.org/lib/> <lang>/examples compiler/cpp/README thrift.apache.org/compiler <http://thrift.apache.org/compilerdebian/README> debian/README thrift.apache.org/debian <http://thrift.apache.org/debiancontrib/> contrib/<topic>/README thrift.apache.org/ <http://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
