v2 of LFE docs site - looking for CSS/HTML help

[Duncan McGreggor]

Hey all,

I've been stalled out on the docs project for several months. I wanted to get something in place that would allow us to version LFE docs. Github produced a pretty sweet docs/API site generator, so I forked that and started making style changes to it:

 * http://docs2.lfe.io/

However, it's been sitting there for months now, in desperate need of CSS and HTML clean-up.

If there's anyone who is both 1) interested in LFE docs, 2) desirous of having a more updated/cohesive/unified LFE doc experience, and 3) has HTML + CSS knowledge, I would *love* your contributions (in the form of PRs).

It would be really wonderful to get this docs site live on http://docs.lfe.io/

The repo is here:

 * https://github.com/lfe/docs2

There are no issues in the tracker, but that's because there are just too many to enumerate right now :-) Once you start poking around http://docs2.lfe.io/ you'll see plenty of them ... !

Thanks for any help,

d

[H Durer]

Interesting.

So what is the vision here?  Is this meant to be the place for documentation?  Or just another place?

There is some documentation in the lfe source under doc/, there are various things on gitbooks and there is docs.lfe.io. 

Is this meant to be the central hub that ties the other things together or are you e.g. considering to move the gitbook docs over to github?

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-e...@googlegroups.com.
To post to this group, send email to lisp-flavo...@googlegroups.com.
Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

[Duncan McGreggor]

Sorry, been *very* busy lately. Responses below:

On Fri, Sep 4, 2015 at 2:59 PM, H Durer <h.du...@gmail.com> wrote:

Interesting.

So what is the vision here?  Is this meant to be the place for documentation?  Or just another place?

This will replace the current http://docs.lfe.io/

The current docs site grew from absolutely nothing, accreting examples, partial docs, various content efforts, etc., over the course of a couple years. Since then, LFE has gained more interest and as a result needs to meet more than the minimal needs it originally targeted.

In particular, the organisation needs to be refocused on the primary goals for the site:

 * providing easy-to-access resources for new learners (regardless if actual content or links to other content)

 * providing quick and intuitive access to reference materials for LFE users

 * providing links to LFE community resources

 

There is some documentation in the lfe source under doc/, there are various things on gitbooks and there is docs.lfe.io. 

Is this meant to be the central hub that ties the other things together

Yup, that's the focus. Some content will be hosted on the new docs.lfe.io, some not.

d

[Eric Bailey]

I love this idea and support it wholeheartedly. I'll fork and poke my nose around. Expect PRs as I get free (read: procrastinatory) time.

Cheers,

Eric

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-erlang+unsub...@googlegroups.com.

To post to this group, send email to lisp-flavo...@googlegroups.com.
Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-erlang+unsub...@googlegroups.com.

[Duncan McGreggor]

Hey all,

It's been a few months since this email went out and about a year since the initial effort was started. Not much has been done in that time, other than a mockup on http://docs2.lfe.io/ (*really* not functional -- just a styling taste).

Robert and I have been chatting about this more recently, and as part of that I've updated all the open tickets for the docs (and closed some):
 * https://github.com/lfe/docs/issues

In short, there is going to be a bit tighter integration between all of the docs (even the bits that are currently hosted elsewhere), improving the use experience overall.

The v2 of the docs site has its own milestone with all the related tickets organized here:
 * https://github.com/lfe/docs/milestones/v2

For anyone wishing to contribute or for a big-picture view of what we're trying to do for the next version of the LFE docs, you'll want to check out "milestone theme" which links to all of the related epics:
 * https://github.com/lfe/docs/issues/62 - Produce v2 of the LFE Docs Site

Milestone epics are here:
 * https://github.com/lfe/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aepic+milestone%3Av2

d

On Friday, September 11, 2015 at 11:14:43 PM UTC-5, Duncan McGreggor wrote:

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-erlang+unsub...@googlegroups.com.
To post to this group, send email to lisp-flavoured-erlang@googlegroups.com.

Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-erlang+unsub...@googlegroups.com.
To post to this group, send email to lisp-flavoured-erlang@googlegroups.com.

[Duncan McGreggor]

I guess I should also mention:

* all existing tickets have been tagged with labels
* should you (including future readers of the mail list archives) be interested in finding areas where you contribute, be sure to filter based on labels

In particular, these might offer nice starting points for identifying where you can contribute:
   - bugs - https://github.com/lfe/docs/issues?q=is%3Aopen+is%3Aissue+label%3Abug
   - enhancements - https://github.com/lfe/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
   - features - https://github.com/lfe/docs/issues?q=is%3Aopen+is%3Aissue+label%3Afeature
   - wishlist - https://github.com/lfe/docs/issues?q=is%3Aopen+is%3Aissue+label%3Awishlist

d

[Duncan McGreggor]

As mentioned in the other thread, I ran into a problem with gh-pages last night that caused me to reconsider how we're going to address the generation of documentation in a sane manner. It also need to be fun for LFE contributors, and let's be honest, many of us don't find hacking on Jekyll or Ruby fun.

One of the biggest blockers for me has been finding a good template to use for our rather complicated info architecture (complicated for the existing Bootstrap templates, that is -- rather run of the mill for your standard docs site). If I give up on trying to squeeze our docs into someone else's vision of a docs site IA, I am no longer blocked on this task.

The thing that has prevented me from going down that route is the gh-pages generation on Github, and choosing something that we could easily drop in place there. As I've seen last night, the benefits of using gh-pages in a highly-customized site are short-lived and not sustainable.

Which brings me back to what would be fun for LFE devs, and make the LFE docs something that we could be *interested* in updating and maintaining: static site generation with LFE. Exemplar actually already has support for spitting out HTML strings from S-expressions. Eric Bailey's Lodox project docs this. I think if we make this sufficiently general (and useful), any project that uses Exemplar can get static site-generation for free. I want to pick Eric's brains on his experience creating Lodox before going down this path, though.

The other related thing I've been examining is information layout and the easy and intuitive access to the multitude of docs that we provide. Robert (Virding) has been pushing me pretty hard on this point, and I've been hesitant to go too far, since we have so many different sources in various locations. BUT! If we are in complete control of the site-generation logic, that would mean we could more easily integrate separate content into a single user/reader experience.

If we decide to explore this option, I'll start with a general template that provides all high-level docs site categories in a menu flush to the left and a content-specific nav menu (e.g., ToC for a given doc, guide, tutorial, etc.) flush to the right. The specialized bits of that template could be pared down to provide general pages, and a landing page has already been created/mocked (it would just need to be converted to Exemplar). With a set of templates in place, we could start with some concrete examples and see how those worked... and then address the remote content integration (a mechanical problem, more than anything else).

All of this is still in flux, so pipe up if you have any thoughts on the matter!

d

P.S. The other thing I've been thinking about is providing automated links to 3rd-party project documentation. These projects would ask to be added, and then they'd need to update their ``lfe.config`` with docs metadata in the "project" section of the config file. The docs tooling would read this and provide links per the individual project metadata, maybe with project blurbs, too.

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-e...@googlegroups.com.
To post to this group, send email to lisp-flavo...@googlegroups.com.

Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-e...@googlegroups.com.
To post to this group, send email to lisp-flavo...@googlegroups.com.

Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.

To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-e...@googlegroups.com.
To post to this group, send email to lisp-flavo...@googlegroups.com.

Visit this group at https://groups.google.com/group/lisp-flavoured-erlang.

[Duncan McGreggor]

Update: Exemplar has just landed experimental support for creating an xmerl-like data structure from the HTML tag macros (the old behaviour of immediately creating strings is still available in the same modules from which it was previously available).

With that yak shaved, I'm ready to start poking about with statically generating some templates for a new site.

d

P.S. My yurt is so full of excellent and fine yak hair that I can't even get in it anymore ... the attached picture shows all the yak hair. That's not snow. The rare White Yak of Code.


​