<div style="font-family: Helvetica; font-size: 13px; ">Hi Ron,<div><br></div><div>I would say the requirements are:</div><div><br></div><div>1) All changes to the documentation should be tracked</div><div>2) Documentation should be easy to change by a non-developer</div><div>3) Documentation should be in a consistent format</div><div>4) Documentation should be able to be published to the XOT package as well as available online</div><div><br></div><div>This implies that:</div><div><br></div><div>1) Documentation source needs to be in a plain text format so it can be version controlled efficiently. Blobs are OK but you can't see what has changed.</div><div>2) Documentation source should be available online (ie. not requiring any specific tools to edit it)</div><div><br></div><div>That's what is pushing me towards the github wiki as the source.</div><div><br></div><div>There's no problem in calling the folder anything we like…</div><div><br></div><div>Deciding what we put into the documentation can be done in parallel with deciding format/location, but the quicker we can get the latter sorted, the less repurposing we'll have to do.</div><div><br></div><div>Mark</div></div>
<div><div><br></div><div>-- </div><div>Mark Berthelemy</div><div>Managing Director</div><div>Tel:<span class="Apple-tab-span" style="white-space:pre"> </span>01773 318 962</div><div>Mob:<span class="Apple-tab-span" style="white-space:pre"> </span>07922 146 761</div><div>Web:<span class="Apple-tab-span" style="white-space:pre"> </span>www.wyversolutions.co.uk</div><div><br></div><div>Wyver Solutions Ltd | Company number: 5731173 Registered in England | Registered address: <span style="font-size: 10pt; ">First Floor, 6 Bridge Street, </span><span style="font-size: 10pt; ">Belper, Derbyshire, DE56 1AX</span></div><div><br></div></div>
<p style="color: #A0A0A8;">On Thursday, 21 November 2013 at 16:23, Ron Mitchell wrote:</p>
<blockquote type="cite" style="border-left-style:solid;border-width:1px;margin-left:0px;padding-left:10px;">
<span><div><div><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta name="Generator" content="Microsoft Word 12 (filtered medium)"><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--><div><p style="margin: 0px; "><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">We already have a documentation folder and I seem to recall we had a valid reason for naming it documentation rather than docs?<o:p></o:p></span></p><p style="margin: 0px; "><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p><p style="margin: 0px; "><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Admittedly that all needs updating and isn't currently in any kind of common format and is also specific to installing and upgrading etc but shouldn't we define what we need/want first before deciding on the format/location?<o:p></o:p></span></p><p style="margin: 0px; "><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p><p style="margin: 0px; "><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Ron<o:p></o:p></span></p><p style="margin: 0px; "><a name="_MailEndCompose"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></a></p><div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm"><p style="margin: 0px; "><b><span lang="EN-US" style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span lang="EN-US" style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> xerte-dev-bounces@lists.nottingham.ac.uk [<a href="mailto:xerte-dev-bounces@lists.nottingham.ac.uk">mailto:xerte-dev-bounces@lists.nottingham.ac.uk</a>] <b>On Behalf Of </b>Mark Berthelemy<br><b>Sent:</b> 21 November 2013 15:53<br><b>To:</b> For developers<br><b>Subject:</b> [Xerte-dev] Documentation process<o:p></o:p></span></p></div><p style="margin: 0px; "><o:p> </o:p></p><div><p style="margin: 0px; ">Hi all, <o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">Rather than setting up a separate wiki for documentation, I'd like to investigate using a sub-repository on Github which is then incorporated into the main Xerte codebase as /docs.<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">The sub-repository would use the Github wiki as its source, so can easily be edited online.<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">The files are in markdown format, so I'll look at adding markdown support via a PHP markdown interpreter, so they can be viewed locally.<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">This approach would allow us to make sure that each release of XOT has a valid, version-controlled set of documentation attached to it.<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">Useful references:<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; "><a href="http://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/">http://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/</a><o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">Can anyone suggest a reason for not going down this route?<o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">Mark<o:p></o:p></p></div><div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">-- <o:p></o:p></p></div><div><p style="margin: 0px; ">Mark Berthelemy<o:p></o:p></p></div><div><p style="margin: 0px; ">Managing Director<o:p></o:p></p></div><div><p style="margin: 0px; ">Tel:<span> </span>01773 318 962<o:p></o:p></p></div><div><p style="margin: 0px; ">Mob:<span> </span>07922 146 761<o:p></o:p></p></div><div><p style="margin: 0px; ">Web:<span> </span><a href="http://www.wyversolutions.co.uk">www.wyversolutions.co.uk</a><o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div><div><p style="margin: 0px; ">Wyver Solutions Ltd | Company number: 5731173 Registered in England | Registered address: <span style="font-size:10.0pt">First Floor, 6 Bridge Street, Belper, Derbyshire, DE56 1AX</span><o:p></o:p></p></div><div><p style="margin: 0px; "><o:p> </o:p></p></div></div></div>
<br><p>This message and any attachment are intended solely for the addressee and may contain confidential information. If you have received this message in error, please send it back to me, and immediately delete it. Please do not use, copy or disclose the information contained in this message or in any attachment. Any views or opinions expressed by the author of this email do not necessarily reflect the views of the University of Nottingham.</p><p>This message has been checked for viruses but the contents of an attachment may still contain software viruses which could damage your computer system, you are advised to perform your own checks. Email communications with the University of Nottingham may be monitored as permitted by UK legislation.</p>
<br></div><div><div>_______________________________________________</div><div>Xerte-dev mailing list</div><div><a href="mailto:Xerte-dev@lists.nottingham.ac.uk">Xerte-dev@lists.nottingham.ac.uk</a></div><div><a href="http://lists.nottingham.ac.uk/mailman/listinfo/xerte-dev">http://lists.nottingham.ac.uk/mailman/listinfo/xerte-dev</a></div></div></div></span>
</blockquote>
<div>
<br>
</div>