Hi Hemanth, Thank you for your considered reply. It seems to me that there are a spectrum of types of documentation, from formal bound manuals of old to tweets. My preference is to strive to embrace social and open up the documentation to be able to be updated by as many people as possible. It would be great if there was a vibrant blog, wiki culture around Atlas in addition to the dev list. I am thinking of Wikipedia as a great example of a self policing community - very much in line with Apache culture.
I notice that there is https://blogs.apache.org/ we could use to blog about developer setups and the like. I guess this approach means there is less control of the documentation but it is more inclusive. I notice Apache Httpd has a wiki where users can contribute https://httpd.apache.org/docs/. You raise a good question around workflow; the question I see is, how much control do we need around it. I can see API references like javadoc or Swagger generated from the code as living in Git and shipping with the product. Guides , designs, dev environment setup, performance tips, integration scenarios, new connectors, FVT testing suites would seem to me to benefit from being in blogs / wikis that many people could create, edit, keep up to date. In the meantime I will create a Twiki file for the Eclipse information, to get it out, all the best, David. From: Hemanth Yamijala <hyamij...@hortonworks.com> To: David Radley/UK/IBM@IBMGB Cc: "dev@atlas.incubator.apache.org" <dev@atlas.incubator.apache.org> Date: 20/12/2016 04:33 Subject: Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on? David, I am including back dev@atlas. I think you are proposing a change to making the edits simpler from the current process, hence would be nice if other people can chime in with their opinion. I guess we get some advantages in doing it the current way: * We can follow all current processes for patch review & commit for docs as for source. Indeed, it would be nice to update documentation whenever sources are updated in the same patch. I know some Apache projects did insist on this practice a while back. * Versioning comes for free and in well defined manners (although, I believe all Wiki systems provide versioning as well - so may not be a big issue) * Docs can be distributed with the source package of Atlas and built and deployed independently. (again may not be a big advantage) In your proposal, I am not still clear on the workflow for a doc update - in particular, how the review / commit would work. So would be nice to understand that a bit more in detail. I am not sure if the choice of doing documentation this way was a deliberate one given the above or similar advantages. Maybe someone more in the know-how can elaborate. Thanks hemanth ________________________________ From: David Radley <david_rad...@uk.ibm.com> Sent: Monday, December 19, 2016 11:11 PM To: Hemanth Yamijala Subject: Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on? Hi Hemanth, Ok thanks. I have registered in twiki.org , made my changes in Microsoft Word, pasted them into twiki sandbox and then switched views to cut and paste the raw format out. This seems to work, though I need to manually change the size of the titles to fit what you have already done. If I read this correctly, I assume the way we should be running this, is to the download and install Twiki on the web server running the Atlas site and then we could expose the rich text Wiki editor on the web site. Maybe only allow committers create and update access for the wiki. The wiki would be the master then not Git. all the best, David. From: Hemanth Yamijala <hyamij...@hortonworks.com> To: David Radley/UK/IBM@IBMGB Cc: "dev@atlas.incubator.apache.org" <dev@atlas.incubator.apache.org> Date: 19/12/2016 15:59 Subject: Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on? ________________________________ David, I have indeed edited files directly.. There are only a handful of syntax elements we need to know and the help for these is available in many online sources (e.g. http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules)< http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules>. Atlas docs can be built by running mvn docs (or something similar) and the files can be checked online. I don't know if there are twiki editors that make this easier to manage. Maybe others know? Thanks hemanth ________________________________ From: David Radley <david_rad...@uk.ibm.com> Sent: Monday, December 19, 2016 9:11 PM To: Hemanth Yamijala Cc: dev@atlas.incubator.apache.org Subject: Fw: Request for Atlas wiki or blog we can put Eclipse setup instructions on? Hi Hemanth, I have not worked with Twiki files before - I assume people do not work directly with the raw format I get from Git (Eclipse shows me the wiki in a preview panel but does not give me a wiki rich text editor). I wondered what development software / process you and community use to create Twiki files. many thanks, David. ----- Forwarded by David Radley/UK/IBM on 19/12/2016 14:55 ----- From: David Radley/UK/IBM To: dev@atlas.incubator.apache.org Date: 19/12/2016 10:33 Subject: Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on? ________________________________ Hi Hemanth, That makes sense. I have raised ATLAS 1401 for this, many thanks , David. From: Hemanth Yamijala <hyamij...@hortonworks.com> To: "dev@atlas.incubator.apache.org" <dev@atlas.incubator.apache.org> Date: 19/12/2016 04:26 Subject: Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on? ________________________________ Hi David, I recommend these instructions be added to the source code under the documentation section. These will be in the Twiki style. Specifically here: https://github.com/apache/incubator-atlas/tree/master/docs/src/site/twiki. We could create a 'developer' section somewhere and start adding things like these in. Indeed, even the technical guide can be under this section, IMO. We can then publish these docs to the website: http://atlas.incubator.apache.org/. Advantage: Precisely for the reason you state, we can keep changing this as the instructions get stale and tag them to a specific release as required. If you think this makes sense, please do open a JIRA ticket and contribute a patch, as usual (modifying or adding files under the docs/src/ folder and committers can take it forward. Hope this makes sense. Thanks Hemanth ________________________________________ From: David Radley <david_rad...@uk.ibm.com> Sent: Sunday, December 18, 2016 4:01 PM To: dev@atlas.incubator.apache.org Subject: Request for Atlas wiki or blog we can put Eclipse setup instructions on? Hi , I have been asked to share the details on how I set up Eclipse of Atlas. I followed detailed instructions prepared by Dave Kantor, which I have slightly embellished. I think it would make sense to put these instructions in the open so more people can benefit from them. Is there a relevant wiki/blog that we can get access to, to put this sort of information on? As the build dependancies change, the instructions will get stale from time to time - so we will need to be able to easily keep them up to date. I suspect other people in the community may have equivalent instructions IntellJ , many thanks , David. Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
