On Fri, Mar 30, 2012 at 7:00 AM, Clay Leeds <[email protected]>wrote:
> Makes sense to me. However, I don't think it's necessary to have all > documentation as such. Perhaps just the Day to day stuff can be translated > (things that are more likely to change). > There aren't too many docs whose content change on a frequent basis. Probably only the status.xml content. > That's my current plan, anyway (although I don't yet know how to make that > happen). Ye olde documentation can remain on xdoc format, or better yet get > converted to Docbook format. > I certainly have no problem with using MD as the source format for README and similar content, and would suggest these be converted to MD. I do have a problem with replacing current XML marked up xdoc sources with MD sources, though I'd be open to considering this on a case by case basis if there is good cause. Regarding XML source formats, right now we have xdoc, and it would take some effort for probably questionable results to convert to another XML schema. Plus that would require some additional learning curve or tool change for authors, so I'm not sure about changing to another XML format. For output formats, obviously we need HTML, but if it is useful to output MD, then I see no problem with someone adding that to the publish build process. I think it is useful to also continue publishing in PDF output format as well, if for no other reason than to exercise FOP. Otherwise, I don't have any strong preferences. For example, I have no love for forrest if another doc management system will be an improvement. So if you can find a way to transition to CMS as the doc management system while still reusing the existing source formats and output formats (modulo the above), then I have no objection to that. Web Maestro Clay > > "My religion is simple. My religion is kindness." > - HH The Dalai Lama of Tibet > > On Mar 29, 2012, at 9:22 PM, Glenn Adams <[email protected]> wrote: > > If I understand correctly, it is proposed that the FOP doc sources be > changed from the current forrest based format (and XML format) to markdown > format. If this is correct, then I would like to voice my objection to > making this change. > > I am all for improving FOP documentation and management process; however, > I am very leery about changing from an XML source format to a non-XML > format, especially one that is as semantically sparse as the markdown > format. > > If a change is to be made, then I would suggest that some XML format > remain as the source format, and that markdown be one of a number of > possible output (publishing) formats. > > Overall, I would prefer spending scarce resources on improving the depth, > breadth, accuracy, and currency of FOP documentation content, rather than > on switching to a different source format, management, or publishing format. > > I also feel it is very important to continue using FOP documentation to > create *some* output format. I am not prepared to give up our dog food, > as that provides one more set of tests on FOP, that would otherwise be > missing. Given the sparseness of FOP test coverage, the more content we > formally run FOP on, the better. > > G. > >
