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



Reply via email to