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
