atlas-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nigel Jones"<nigel.l.jo...@gmail.com>
Subject Re: Twiki documentation
Date Fri, 18 Aug 2017 00:20:05 GMT
I think there's perhaps 2 areas of discussion here

a) Standards for OMAS interfaces

I did indeed initially place a list for review on the Atlas wiki. I do agree that we should
keep this as an external view of the project rather than have potentially confusing work in
progress, hence the thought of using JIRA+review tool. A text-like format seems to work best
in the review tool as then comments can be in-situ (I believe - not used it before) as they
would for code. Hence the reference to text like formats like twiki, markup etc (but see below)

I'm happy to place the doc wherever we see as useful ;-) The rational for suggesting the existing
twiki was that it is docs that have gone through a form of review process and are seen as
more 'definitive' than individual contributions on the wiki. This then also fits well with
the principle of building a patch which includes files under SCM, but that shouldn't be the
leading reason

I'm still inclined to think this material does fall into this more definitive category? 

but ....

b) Existing twiki docs

We have some material today that could do with updating in the twiki. It includes references
to the Atlas architecture, installation, quick start, APIs. If the suggestion for a) is that
the wiki is better, I wonder if that also applies to at least some of this content... maybe
other than the APIs, in which case we may wish to also move that to the wiki

Alternatively, if we feel they should remain with the source code then I think the format
question remains as twiki (to me at least) seems a somewhat outdated format


I will continue updating the tiki-oriented patch tomorrow in any case -- since it's a text
oriented format that makes it suitable for review/comment, and we can agree on the content.
Hopefully that helps... Then in parallel we can figure out our doc strategy of SCM-managed
doc content vs wiki, plus format of any SCM oriented content?

Nigel.

On 2017-08-17 10:18, Mandy Chessell <mandy_chessell@uk.ibm.com> wrote: 
> Hello Nigel,
> I don't think that Twiki is the right approach - I think we should keep 
> this on the confluence wiki to make it easy to find and enhance.  This is 
> more than internal documentation.  It not only helps developers build new 
> OMAS APIs but also helps people to understand the philosophy behind them - 
> which helps them consume the APIs.
> 
> When we talked about developing these standards I suggested that the 
> development of the standards should be done through the Jiras - just like 
> all our other design documentation and when we have some agreement then 
> publish to the confluence wiki.  The publishing process can be iterative - 
> but the contents of the wiki should be of a good quality rather than rough 
> notes because it is our shop window for people looking to adopt our 
> technology.
> 
> I thought you were going to use the review tool to gather standards 
> together?  Alternatively, use a word doc linked to the Jira that people 
> can mark up.
> 
> All the best
> Mandy
> ___________________________________________
> Mandy Chessell CBE FREng CEng FBCS
> IBM Distinguished Engineer
> 
> Master Inventor
> Member of the IBM Academy of Technology
> Visiting Professor, Department of Computer Science, University of 
> Sheffield
> 
> Email: mandy_chessell@uk.ibm.com
> LinkedIn: http://www.linkedin.com/pub/mandy-chessell/22/897/a49
> 
> Assistant: Janet Brooks - jsbrooks12@uk.ibm.com
> 
> 
> 
> From:   "Nigel Jones" <nigel.l.jones@gmail.com>
> To:     <dev@atlas.apache.org>
> Date:   17/08/2017 09:15
> Subject:        Twiki documentation
> 
> 
> 
> In https://issues.apache.org/jira/browse/ATLAS-2049 I am aiming to 
> document some thoughts around standards for our new proposed OMAS 
> interfaces. Since this is really internal documentation and tightly 
> related to the code I think (and this was suggested by others too) that 
> this should be added into the twiki structure in the source tree. That's 
> fine and I'll do exactly that with discussion in ATLAS-2049
> 
> HOWEVER editing support for twiki is a little limited (for example there's 
> no easy to use plugin for IntelliJ that I found), and though the format is 
> a relatively simple markup, I wondered if better options might be to 
> either go with:
> * HTML - plenty of editor choice, some pages & api ref already are in this 
> form
> * markdown - this is increasingly becoming standard ie our README.md files
> 
> We don't have that much content in the twiki, and moving forward I do 
> think it would be useful to extend/update with "reference" material, so it 
> could be an opportune moment to consider what we'd like to do in future.
> 
> I'd err myself towards markdown as it preserves the simple text 
> readability whilst being flexible and having simple editor support
> 
> 
> 
> 

Mime
View raw message