Best Practices for Bundling Documentation

Hi Evan

Depending on the size of the documentation.
- if you have a kind of tutorial I would go (and I can help) for a
pillar booklet or a chapter.
- else class comments are simply cool with examples


stef

On Sat, Aug 5, 2017 at 2:19 AM, Evan Donahue <[hidden email]> wrote:

Hello,

The projects are a logic programming and machine learning system respectively, so they probably warrant more involved tutorial-style documentation. I will take a look at the Pillar docs, but just to think ahead a bit, assuming I write up some docs in Pillar, what would be the best way to distribute those? Can they be packaged with the code or would the docs be outside the image? If outside, where do people tend to host them?

Thanks,
Evan

Hello evan

Cool I want to read them!
If you have your code in github you can include pillar files there and
with travis build the pdf as I did for the booklets.
I prefer to separate tutorials from code.

I would go for
     MyStuff
     MyStuffTutorial
or


This way readers can get the pdf
https://github.com/SquareBracketAssociates/Booklet-BuildingMemoryGameWithBloc
or
https://github.com/SquareBracketAssociates/Booklet-Mocking

I can help you to set it up.
After you booklet can be published on the Pharo books page too.

stef


On Sun, Aug 6, 2017 at 1:34 AM, Evan Donahue <[hidden email]> wrote:

or
   MyStuff
   MyStuff/Tutorial

On Sun, Aug 6, 2017 at 11:00 AM, Stephane Ducasse
<[hidden email]> wrote:

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:

Ok, thanks.

Gracias, pronto lo reviso.