Re: [Pharo-users] Best Practices for Bundling Documentation

[Evan Donahue]

Gracias, pronto lo reviso.



--
View this message in context: 
http://forum.world.st/Best-Practices-for-Bundling-Documentation-tp4958788p4959140.html
Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

Re: [Pharo-users] Best Practices for Bundling Documentation

[Evan Donahue]

Ok, thanks.



--
View this message in context: 
http://forum.world.st/Best-Practices-for-Bundling-Documentation-tp4958788p4959139.html
Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

Re: [Pharo-users] Best Practices for Bundling Documentation

[Offray Vladimir Luna Cárdenas]

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

Re: [Pharo-users] Best Practices for Bundling Documentation

[Stephane Ducasse]

or
   MyStuff
   MyStuff/Tutorial

On Sun, Aug 6, 2017 at 11:00 AM, Stephane Ducasse
 wrote:
> 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  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
>>
>>
>>
>> --
>> View this message in context: 
>> http://forum.world.st/Best-Practices-for-Bundling-Documentation-tp4958788p4958910.html
>> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>>

Re: [Pharo-users] Best Practices for Bundling Documentation

[Stephane Ducasse]

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  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
>
>
>
> --
> View this message in context: 
> http://forum.world.st/Best-Practices-for-Bundling-Documentation-tp4958788p4958910.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>

Re: [Pharo-users] Best Practices for Bundling Documentation

[Evan Donahue]

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



--
View this message in context: 
http://forum.world.st/Best-Practices-for-Bundling-Documentation-tp4958788p4958910.html
Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

Re: [Pharo-users] Best Practices for Bundling Documentation

[Stephane Ducasse]

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  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

[Pharo-users] Best Practices for Bundling Documentation

[Evan Donahue]

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