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/man... [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.m... [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