Re: Request for Atlas wiki or blog we can put Eclipse setup instructions on?

[Nigel Jones <ni...@cherrybyte.me.uk>]

Interesting question!

I would agree that there's both fairly formal, "definitive" documentation
such as APIs, specifications, and I think internal designs which are likely
fairly technical, written by core contributors..reviewed... and having them
within the source makes sense to me.. I think I'd probably add some of the
tests you mention David? The tar file, or a git mirror is then the entire
project..

But then above this the more consumer-centric docs, tips, howto are
probably much more collaborative and opinion based rather than definitive.
Not formally reviewed necessarily..  Written by a more diverse community we
hope. In fact probably spread across multiple places - user blogs, apache
blogs, twitter posts (links), linked in etc...Would a ap

The eclipse instructions somewhat straddle the boundary. If it's just one
person using it then an adhoc blog is a starting point, but if it's useful
for many coders then I'd personally be inclined to check it in to the
source, as it is today....

For the httpd wiki you mention it looks like they do have it checked into
SCM -- subversion, which is similar to Atlas's formal docs. I wonder if,
like this, there any more publically open wikis apache projects use?

Nigel.


On Tue, 20 Dec 2016 at 11:21 David Radley <da...@uk.ibm.com> wrote:

> 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 <hy...@hortonworks.com>
> To:     David Radley/UK/IBM@IBMGB
> Cc:     "dev@atlas.incubator.apache.org" <de...@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 <da...@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 <hy...@hortonworks.com>
> To:        David Radley/UK/IBM@IBMGB
> Cc:        "dev@atlas.incubator.apache.org"
> <de...@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 <da...@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 <hy...@hortonworks.com>
> To:        "dev@atlas.incubator.apache.org"
> <de...@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 <da...@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
>
>