-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 12/01/11 21:48, Jan Just Keijser wrote: > Hi David, > > David Sommerseth wrote: >> -----BEGIN PGP SIGNED MESSAGE----- >> Hash: SHA1 >> >> >> Hi folks! >> >> This is a little cry for help from us playing with the OpenVPN code. >> >> We have a quite good man page today with a lot of information. But >> maintaining it and to make sure it is up-to-date with all the features >> OpenVPN supports is often not high up on the priority list. In >> addition, the current format (one single file, in pure man page format) >> is getting harder and harder to maintain as well. >> >> So, we're hoping some people with some English skills is interested to >> help out improving this situation. What we immediately would like to >> see is something along these lines: >> >> * Move the man page to a better format than the pure man page format. >> Are there some good tools/formats like ascii2man or DocBookXML which >> could help easing the maintenance of our documentation? >> >> * Split up the documentation into more focused sections, like >> - main openvpn page (kind of like openvpn.8 today) >> Gives an executive overview over OpenVPN, features and references >> to the other documentation pages. A bonus would be if it easily >> can produce other formats in addition, like HTML, PS/PDF, ePub. >> >> - openvpn common options >> Gives information about the common options openvpn has, which is >> useful on both server and client instances. F.ex. --keepalive, >> --tls-auth, --cert, --key, --ca, etc >> >> - openvpn server options >> Describes only the options which are relevant for openvpn servers >> >> - openvpn client options >> Describes only options useful for openvpn clients >> >> - openvpn plug-ins >> Describes the different script plug-in hooks and environment >> variables available to scripts and plug-ins written in C >> >> * Review the contents of all the documentation, check their accuracy >> - Make sure no options are not available in OpenVPN 2.2 or later >> - Make sure no options are missing in the documentation, which is >> available in the source code (options.c is a good reference) >> >> * Review and check if all external references >> - Make sure all references to external sources, like web-sites, are >> still available, valid and relevant in the document context >> - Find other external resources which are worth including. >> >> (These points are not carved into stone, but is more like a guideline of >> what needs to be considered) >> >> This task should hopefully not require too much in-depth development >> knowledge. It should be user-focused, so that we avoid using terms and >> details which is not so easy to understand. What I'm saying is that >> this documentation can be more useful and readable if users are involved >> in this process. >> >> If someone are willing to step up and take a lead, that would be great! >> Further, discussions and reviews of the document changes should >> probably happen on the openvpn-users mailing list. That way, it might >> be easier for users to review the documentation and provide feedback. >> >> We don't want this to just be a solo-project from someone in our OpenVPN >> community, so we hope more people can help out and contribute, also if >> you don't consider yourself a developer. >> > I'd be willing to contribute but I don't see myself leading this effort > right now (due to other obligations).
That's just fine! And I presume you're not the only one loaded with other tasks. I believe if every one contributes a little bit according to available time, big efforts will be achieved in the end. Just reading suggestions and giving comments are also much appreciated! > As for the document format: if we want users to contribute then we > should not opt for a too-difficult format that users would have to learn > before being able to contribute. Docbook and/or texinfo are nice for > Linux users but you'd scare away most Windows/Mac users. > What about plain simple OpenDoc (odf) ? I've been thinking about that we need to lower the level for contributing documentation. ODF isn't such a bad suggestion, after all it is XML based and with strict style usage it should be possible to do some script magic on these files. However, why not lower the bar even more? (And I do see Karl O. Pinc's comment as well, people would need to install ODF compliant software) Krzee on IRC simply asked, why not use wiki for this purpose? I personally think that is a very good idea! For the reasons: * Simple formatting but still some structured way of organising the contents * Many users are familiar with wikis, and the learning curve is usually low. * No special software required, all you need is a browser * No git knowledge needed * Revision control is built into the wiki (and on community wiki, login is required - so we can trace who did what) It should be possible to write a little script which parses the wiki (page content) source text and makes man/html pages and example files based on this. This could be done before each release. The drawback is that the wiki markup might be too flexible (too many features) and the parsing script might get complicated. Other alternatives is to consider plain text variants like markdown[1]. This style is also very close to the wiki style markup as well. A third alternative is Docutils/reStructuredText[2]. kind regards, David Sommerseth [1] <http://daringfireball.net/projects/markdown/>, <http://en.wikipedia.org/wiki/Markdown> [2] <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>, <http://docutils.sourceforge.net/docs/user/tools.html>, <http://en.wikipedia.org/wiki/ReStructuredText> -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iEYEARECAAYFAk0u2AUACgkQDC186MBRfrpovwCggCGdW4cychuequFMAjzL28Ez rekAnA9AWGUHaY/BkquDmN6DZ59VfiPy =WyDq -----END PGP SIGNATURE-----
