On Jan 10, 2018 6:43 PM, "Nash, George" <[email protected]> wrote:
Gregg, What tool are you using to render/edit the documents? Are you using DITA Open Toolkit? Or some other tool? There are two open source tks I know of, dita-ot and ditac from XMLMind. the readme has links to both. I tend to prefer dita-ot but only because I like its default stylesheet for PDF. XMLMind has an awesome XML editor but the stylesheets for ditac are not so great. They both have HTML output stylesheets but both are very elementary. Of course the nice thing is you can create your content without worrying about style. You can always write customized stylesheets for either engine, later. Hth G P.s. if anybody wants to start in, just contact me if you have trouble. Thanks, George Nash *From:* [email protected] [mailto: [email protected]] *On Behalf Of *Gregg Reynolds *Sent:* Monday, January 8, 2018 2:24 PM *To:* iotivity-dev <[email protected]> *Subject:* Re: [dev] new documentation project P.S. if XML makes you puke, the DITA Open Toolkit also supports markdown of some kind. I've never used it, but there it is. You have no excuse. On Jan 8, 2018 2:52 PM, "Gregg Reynolds" <[email protected]> wrote: I've started a documentation project in case anybody wants to help out. It uses DITA. Just a skeleton so far but there is some info on security there. Nice things about DITA: - You write doc in small chunks that can be easily reused and reorganized. That means you can contribute easily without having to worry about document structure. - It has sophisticated vocabularies for documentation. - It's reasonably easy to get going by copying from existing articles. (The markup is very similar to HTML) - Two open source implementations. - Automated indexing, cross-referencing, etc. - Multiple output formats. - Customizing styles is (relatively) easy (if you know XSL) - It's much easier to manage DITA doc than a Wiki. This is just getting started so it's pretty skeletal, but what is there demonstrates indexing, glossary, and organization of content nodes using a main ditamap file. I've begun filling in the Security part; it's still thin but you can see the narrative stragegy (I hope). Again, reorganizing the main doc is trivial, so if you have other ideas about how to organize the material it is easy to experiment. See https://github.com/OpenOCF/ocfguide. PDF output is in the ./out directory. You can generate HTML output easily, but the stylesheets are pretty primitive so I have not done so. If you lament the state of Iotivity documentation now's your chance to help improve it. If this ever turns into something useful it could be transferred to the Iotivity website, and a customized stylesheet written to generate HTML. HTH, Gregg
_______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
