librelist archives

« back to archive

Re: [leiningen] Leiningen book?

Re: [leiningen] Leiningen book?

From:
Phil Hagelberg
Date:
2013-09-02 @ 02:14
Gregg Reynolds writes:

> https://github.com/greynolds/leiningen-doc

Wow, that's a very ambitious effort. The output is quite nice too.

> If you're not familiar with DITA a little searching online will produce
> useful info.  There are lots of advantages to using DITA to make "real"
> documentation.  Markdown is fine for quick and dirty doco, but it's not
> really appropriate for the real thing.

I agree that technically speaking, Markdown is very deficient to say the
least. But documentation, at least in the case of Leiningen, is
primarily a social concern; we don't have very demanding technical
requirements, but the fact that anyone can contribute documentation with
just a couple steps is highly prized. I clicked through on the
leiningen-doc repo to try to find out how to build it for myself and got
seven or eight links in without finding what I was looking for. IMO a
barrier to contribution like that should not be introduced lightly.

I'd be happy to talk about specific areas in which the documentation
could improve. Apart from the content itself, I think cross-references
in particular are probably the biggest missing piece technically and
could possibly be addressed by making another pass over the existing
~2000 lines of markdown with something like pandoc without sacrificing
the github rendering and familiarity we currently enjoy. And of course,
as always specific gaps in content should definitely be addressed; we
can track those as github issues or on this thread.

thanks,
Phil

Re: [leiningen] Leiningen book?

From:
Gregg Reynolds
Date:
2013-09-02 @ 03:42
On Sun, Sep 1, 2013 at 9:14 PM, Phil Hagelberg <phil@hagelb.org> wrote:

>
> Gregg Reynolds writes:
>
> > https://github.com/greynolds/leiningen-doc
>
>
> I agree that technically speaking, Markdown is very deficient to say the
> least. But documentation, at least in the case of Leiningen, is
> primarily a social concern; we don't have very demanding technical
> requirements, but the fact that anyone can contribute documentation with
> just a couple steps is highly prized.


The hypothesis is that once a basic DITA structure is in place it would
remain relatively easy for anybody to contribute, just by cut-and-paste.
 The tags are mostly self-evident.  But nonetheless you'd want somebody to
act as editor-in-chief who could assist people with markup.  (Whether or
not adoption of DITA for the official documentation makes sense is of
course a separate issue.  DITA-based pedagogical material or users guides
are compatible with keeping the tech reference doco in markdown.)

One major advantage to DITA, which I did not foresee clearly when I
started, is that it really facilitates good structure by making it easy to
quickly try out structural variations.  Basically you have a bunch of atoms
(topics, concepts, tasks, references) and you can use a map to rearrange
them quickly.  Hierarchy is not hardcoded in node content but is specified
externally.  Pretty cool once you get the hang of it.


> I clicked through on the
> leiningen-doc repo to try to find out how to build it for myself and got
> seven or eight links in without finding what I was looking for. IMO a
> barrier to contribution like that should not be introduced lightly.
>

Sorry, my bad.  I've added some instructions to the main README.


>
> I'd be happy to talk about specific areas in which the documentation
> could improve. Apart from the content itself, I think cross-references
> in particular are probably the biggest missing piece technically and
> could possibly be addressed by making another pass over the existing
> ~2000 lines of markdown with something like pandoc without sacrificing
> the github rendering and familiarity we currently enjoy. And of course,
> as always specific gaps in content should definitely be addressed; we
> can track those as github issues or on this thread.
>

Ok, I'll see what I can do along these lines as I proceed.  But in the
course of thinking about Leiningen and working with DITA for a few days,
I've decided that my short-term goals are to 1) finish a decent draft
structure for leiningen-doc (something feasible as a real proposal), and 2)
finish up most of the basic high-level ideas I've come up with regarding
how to explain Leiningen, some of which you can see in the current PDFs.
 The basic idea is to start with a good description /analysis of the sorts
of problems L addresses, in abstract/schematic terms, then describe the
"Leiningen mode of thinking" about them and how to solve them, then move to
specific examples.  Something like that, anyway, I know it's kind of vague
but the latest version at leiningen-doc may have enough content to give you
the idea.

In any case, that's the "user guide" story, which is as much pedagogical as
descriptive, and can be told in lots of different ways - the more the
merrier, IMO.  The "tech reference" story, which I think is what you have
in mind above, is a rather different kettle of fish.  Only one needed,
which should be accurate and complete (and probably minimal). So I'll keep
my eye out for any deficiencies in the current official doc as I go.

Knuth wrote the following in the MetaFONT book:

WARNING: Type design can be hazardous to your other interests. Once you get
hooked, you will develop intense feelings about letter- forms; the medium
will intrude on the messages that you read. And you will perpetually be
thinking of improvements to the fonts that you see everywhere, especially
those of your own design.

Same goes for document and documentation design using stuff like DITA, in
my experience.

Thanks,

Gregg