[Xerte-dev] Re: Documentation process

[Mark Berthelemy]

Hi Ron,

I would say the requirements are:

1) All changes to the documentation should be tracked
2) Documentation should be easy to change by a non-developer
3) Documentation should be in a consistent format
4) Documentation should be able to be published to the XOT package as well as available online

This implies that:

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.
2) Documentation source should be available online (ie. not requiring any specific tools to edit it)

That's what is pushing me towards the github wiki as the source.

There's no problem in calling the folder anything we like…

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.

Mark  

--  
Mark Berthelemy
Managing Director
Tel: 01773 318 962
Mob: 07922 146 761
Web: www.wyversolutions.co.uk

Wyver Solutions Ltd | Company number: 5731173 Registered in England | Registered address: First Floor, 6 Bridge Street, Belper, Derbyshire, DE56 1AX


On Thursday, 21 November 2013 at 16:23, Ron Mitchell wrote:

> We already have a documentation folder and I seem to recall we had a valid reason for naming it documentation rather than docs?
>   
> 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?
>   
> Ron
>   
> From: xerte-dev-bounces at lists.nottingham.ac.uk [mailto:xerte-dev-bounces at lists.nottingham.ac.uk] On Behalf Of Mark Berthelemy
> Sent: 21 November 2013 15:53
> To: For developers
> Subject: [Xerte-dev] Documentation process
>   
> Hi all,  
>  
>   
>  
> 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.
>  
>   
>  
> The sub-repository would use the Github wiki as its source, so can easily be edited online.
>  
>   
>  
> 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.
>  
>   
>  
> This approach would allow us to make sure that each release of XOT has a valid, version-controlled set of documentation attached to it.
>  
>   
>  
> Useful references:
>  
>   
>  
> http://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/
>  
>   
>  
> Can anyone suggest a reason for not going down this route?
>  
>   
>  
> Mark
>  
>   
>  
> --  
>  
> Mark Berthelemy
>  
> Managing Director
>  
> Tel:     01773 318 962
>  
> Mob:   07922 146 761
>  
> Web:   www.wyversolutions.co.uk (http://www.wyversolutions.co.uk)
>  
>   
>  
> Wyver Solutions Ltd | Company number: 5731173 Registered in England | Registered address: First Floor, 6 Bridge Street, Belper, Derbyshire, DE56 1AX
>  
>   
>  
>  
>  
>  
> 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.
> 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.
>  
> _______________________________________________
> Xerte-dev mailing list
> Xerte-dev at lists.nottingham.ac.uk (mailto:Xerte-dev at lists.nottingham.ac.uk)
> http://lists.nottingham.ac.uk/mailman/listinfo/xerte-dev
>  
>  


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.nottingham.ac.uk/pipermail/xerte-dev/attachments/20131121/b1e23696/attachment.html>