Hi Evan, I have been working on the issue of documentation in Pharo, including bundling. So here comes my take on that. Sorry if it sounds a little bit self-promotional, but I'm really passionate about the almost unknown and unexplored possibilities of Pharo for documentation.
Grafoscopio is a tool for interactive documentation, data storytelling and reproducible research made in Pharo [1]. You can see a short video of how it looks and what it does in [1a]. With Grafoscopio, you can have a single document for your different documentation tasks from a complete book, to a small tutorial, to something in between, to a small outline with just notes and links, etc. Documents in Grafoscopio are organized as structured as trees, which gives them hierarchy and sequence. Grafoscopio User Manual [2] was made, of course, in Grafoscopio (we love self-referential systems :-P). Grafoscopio uses the powerful, versatile, well maintained, easy to setup and configure Pandoc [3] to export documents to several formats. You can add custom templates and options to your documents in several formats (see for example [4]). All document information, including setup options can be hold in a single Grafoscopio file, called notebook, and you can even choose if you want to keep something in the notebook that will be hidden in some exportation format and use/define special words and tags to control the way the documents are traversed and exported (see the %keywords part of the manual). Grafoscopio has preliminary integration with the minimalist and self contained Fossil[5], to support collaboration and reproducible research and also with Zotero bibliographic management system. [1] http://mutabit.com/grafoscopio/index.en.html [1a] http://mutabit.com/repos.fossil/alvicoda/ [2] http://mutabit.com/repos.fossil/grafoscopio/doc/tip/Docs/En/Books/Manual/manual.pdf [3] http://pandoc.org/ [4] http://mutabit.com/repos.fossil/piamed/doc/tip/Libro/libro.pdf [5] http://fossil-scm.org/ [6] https://www.zotero.org/ To package manuals and tutorials, there is a GrafoscopioDocumentation object that defines a (Fossil) documentation repository and the files there that are part of a documentation project. GrafoscopioDocumentation knows how to query and update the repositories using the standard Fossil JSON API. That's the way I use to package documents about several projects made in Grafoscopio, including its manual, and the Dataviz[6] project and the upcoming Data Journalism Manual [7]. [6] http://mutabit.com/repos.fossil/grafoscopio/doc/tip/Packages/Dataviz/intro.md [7] http://mutabit.com/repos.fossil/mapeda/index We have an small, active and diverse community of people using and extending Grafoscopio in our hackerspace [8], that includes librarians, journalists, activists, philosophers and others and in our Spanish mailing list we also get and answer English mail, if you need any support (see [1] for community links). [8] http://hackbo.co/ So, give a look to Grafoscopio for your documentation needs and let us know if you need any help with it. Cheers, Offray On 04/08/17 19:19, Evan Donahue wrote: > Hello, > > I'm working on cleaning up a couple of projects for release, and I was > wondering what the best practices were for including appropriate > documentation with projects. Should I just drop a text blob in a > prominent class comment? Is there a tool for structuring > documentation? Is documentation typically kept separate from the code? > Seems natural to include it so you never have to leave the image, but > I'm not sure what most people do. > > Thanks, > Evan
