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 <[email protected]> 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: [email protected] > LinkedIn: http://www.linkedin.com/pub/mandy-chessell/22/897/a49 > > Assistant: Janet Brooks - [email protected] > > > > From: "Nigel Jones" <[email protected]> > To: <[email protected]> > 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 > > > >
