Re: [lisp-flavoured-erlang] LFE Docs Update (was: The state of LFE ... and a New Hope)

[Duncan McGreggor]

Hey all,

There's been increasing interest in helping out with the LFE docs, so I've put some time into the infrastructure in the hopes of lowering the barrier to entry for contributions, and well, making contributions something more than just random madness.

Highlights:

1) The latest work will soon be merged from http://docs3.lfe.io/ to http://docs.lfe.io/

   - outwardly, this won't look any different, other than a chance in URL

   - current stable docs will be available at http://docs.lfe.io/current

   - this is also where http://docs.lfe.io/ redirects to

   - the biggest deal with this move, though, is that there will be a http://docs.lfe.io/dev

   - the /dev path will be the latest design, have links to all versions of docs, etc.

   - it will also be where all the contributions are made

2) Once we have a minimally useful http://docs.lfe.io/dev, we can promote it to /current

3) There are new instructions on how to make contributions

    - the instructions are technically-oriented

    - they describe (briefly) what you need to create

    - as questions arise, we can update the instructions to be more thorough

4) Templates are now being used (ErlyDTL, based on Django Page Templates)

5) SASS for CSS-generation is now being used consistently

What's Not Done:

* Pretty much everything else ...

* The links on the front page don't go anywhere, since the content hasn't been migrated

* Lots of new content needs to be created

* No support for .md files yet

* No support for slurping Gitbooks content yet

* Etc., the list goes on and on

But the new infrastructure that is in place provides a well-defined approach for adding any new content and a context for making improvements.

Type of help needed:

 * Converting old content to the new site

 * Creating new content (there are tickets for this)

 * Reviewing the SASS/CSS that we've created

 * Performing UI / UX QA testing on mobile platforms

 * Creating tickets for anything related to the above, and other things

 * Picking up tickets, submitting PRs, etc.

I'm hoping to merge the latest work into the docs repo tonight sometime ... I'll send another note when that's all set up and ready!

d

On Sat, Oct 15, 2016 at 11:04 AM, Duncan McGreggor <dun...@mcgreggor.org> wrote:

On Fri, Oct 14, 2016 at 2:11 PM, Claudia Doppioslash <claudia.d...@gmail.com> wrote:

 

Yes, the site does need a reworking and if someone was to take on this project it would be a big boost and I would be very grateful. I have more or less translated the Erlang tutorial to LFE but at the moment it is the gitbook section but it should be moveable to a future site. Work is also being done to write clojure inspired modules for LFE and one has been included and as soon as I get the time[*] I will pull the update.

I could help with the website.

Claudia, this is *great* news -- thanks!

What is needed? 

Oh, soooo much. First, a note on philosophy:

* open source is volunteer-driven, so volunteers need to be provided with the freedom of working on the things they enjoy using the tools they love.

I mention this because I'm going to share some links to open web site (and related infrastructure) tickets ... they have a lot of detail in them about tool choice, development priorities, etc. That was done when I was working on this stuff exclusively. In accordance with the philosophical statement above, any contributors have every right to make different propositions, select different tools, etc.

Ultimately, what counts, is the finally delivery of some bit of functionality (site, docs, code, etc.) to the community, and that final piece is evaluated in the PR (as opposed to the tool selection, etc., being evaluated. (If you want to make big directional changes, just share some links to mockups or templates ahead of time -- that will lighten the load during the PR/QA/review cycle.)

So, with the following links, know that they are guidelines and that have you the freedom to chose your own path forward to helping the LFE community in whatever contributions bring you the most joy :-)

Tickets:

 * There are almost 60 open tickets here

 * Link: https://github.com/lfe/docs/issues

 * That view is almost useless ...

Milestone:

 * The v3 release of the docs is the next milestone (... and has been for a while :-( ...)

 * Link: https://github.com/lfe/docs/issues/62

 * This view is the most useful top-level view right now

 * Each of the tickets linked in that description is an epic

Epics and other Tickets:

 * Epics each have their own list of task and feature tickets (and sometimes sub-tickets)

 * Some of the epics have been closed, such as infrastructure decisions and information architecture -- feel free to re-open if you want to change directions anywhere

Current status

 * The following WrapBootsrap (3) theme has been developed:
    - http://docs3.lfe.io/examples/theme.html

 * The following landing page was the last look&feel task in progress (part of the #66 epic):
    - http://docs3.lfe.io/examples/prototype-landing.html

    - It explores top nav, footer, "splash" jumbotron, highlevel above-the-fold sections, and a detailed list of sections/subsections below-the-fold (tied in with the IA epic, #49)

    - This was part of this ticket set: https://github.com/lfe/docs3/issues/11

    - Which was linked in this epic: https://github.com/lfe/docs/issues/66

Additional Notes
 * As you can see, there is a zoo of tickets (with *some* attempt at organization) around this work ... could be much more clearly organized

 * I'm no longer sold on converting HTML to S-expressions. That may be over-LFE-ing and limiting our pool of site contributors

 * I'm no longer sold on inching towards a CMS-style approach; raw HTML might be fine for now, and possibly indefinitely (it's not like we'd be changing content at the rate that news sites do)

 

Looking forward to anything you feel like helping out with!

d

I have some good news anyway. My boss and I have been working hard to try and spread LFE inside Erlang Solutions and we have it included in the Erlang Ecosystem. See the logo at the end (which needs to be rotated 45 degrees). I always mention it when talking about the ecosystem. As part of a consulting job we are doing for a client in Elixir I should be able to a section in LFE. I will know in 2 weeks time. We have some really cool pictures with 3d versions of the cube as well.

Cool :) 

--

Claudia Doppioslash

@doppioslash

http://www.doppioslash.com

http://www.lambdacat.com   | Functional Programming

http://www.shadercat.com    | Shader & Graphics Programming

--
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+unsubscri...@googlegroups.com.
To post to this group, send email to lisp-flavoured-erlang@googlegroups.com.
Visit this group at https://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.