atlas-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Radley <david_rad...@uk.ibm.com>
Subject Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on?
Date Tue, 20 Dec 2016 11:20:33 GMT
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 <hyamijala@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_radley@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 <hyamijala@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_radley@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 <hyamijala@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_radley@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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message