Thanks, Matt. I’ve been going through and doing a bit of research to see where the different parts are and how I could contribute.
Looking at Viktor’s comments (http://marc.info/?l=openssl-dev&m=139830754423978&w=2), he points out that "too often a new feature impacts multiple documents, and API documentation requires more text than typically produced by doxygen and the like” And there's such a large amount to be backfilled, it needs to be an organized effort as the backfilling will be done in parallel with code updates and improvements. I'm worried that the catch-up work will never fully catch up. Taking dkg's suggestion to "organizing a documentation sprint to do this kind of backfill labor in an organized and complete way", maybe there's a better way to get this done. Diff As You Type: Give me the weekend to flesh out a demo of a collaborative tool to work on documentation (https://app.box.com/s/45w2xw1iwu9w0wsxx3zc). It's currently functional enough to get the above screenshot. The Basic Idea: Make it easier for anyone who uses the documentation to make corrections, flag errors, additions, and submit patches without them ever needing to know how or which documentation system is in use. Possible Workflow: 1. I need to look up documentation 2. Look it up on mdoc.io (its the first name i came up with) 3. See some missing, incorrect, needs clarification, or a good example 4. Make the correction, patch shows up on the right 5. If logged in, Hit submit, patch is submitted Otherwise, copy+paste & submit patch manually Sprinkle in some github api magic and it may even be relative easy to make references to specific areas of code within the documentation. What are your thoughts? Can something like this be useful? -Phong On May 9, 2014 at 11:37:18 AM, Matt Caswell ([email protected](mailto:[email protected])) wrote: > On 9 May 2014 18:03, Phong Long wrote: > > Hi Dev (sorry if this is a dupe, sent to dev w/ wrong email) > > > > I’ve been reading up on what it'll take to keep the documentation > > up to date as it's something I can do to contribute, but I’m a bit > > confused about which format to use. The existing documentation is > > in pod format, but should they be in mdoc? > > > > I found one thread on netbsd mentioning openssl's pod format: > > http://mail-index.netbsd.org/tech-userlevel/2009/04/21/msg002053.html > > > > and this discussion on openbsd ports while looking @ textproc/pod2mdoc: > > http://comments.gmane.org/gmane.os.openbsd.ports/66762 > > > > indicates that there is a clear need for converting old pods to mdoc. > > > > caveat section for pod2mdoc(1) admits that: > > By way of being a presentational language, POD is not well-represented > > by mdoc(7). Semantic content must be inferred and may be wrong. > > > > Just so that I get started down the right path, should the pod > > files be converted to mdoc and continue from then on in mdoc? Or leave > > as is and continue with pod? > > > I'm not crazy about converting from pod to mdoc. If we are going to do > anything with the documentation then my preference would be to go with > with a source based system, e.g. doxygen. > > This was discussed recently: > http://marc.info/?l=openssl-dev&m=139832883828644&w=2 > > It's on my TODO list to look at this further....but I've been a little > distracted with trying to get some of the RT tickets closed off. I > promise I'll try and find some time! > > Until then, POD is it. > > Matt > ______________________________________________________________________ > OpenSSL Project http://www.openssl.org > Development Mailing List [email protected] > Automated List Manager [email protected] ______________________________________________________________________ OpenSSL Project http://www.openssl.org Development Mailing List [email protected] Automated List Manager [email protected]
