Documentation thoughts and tool

131 views
Skip to first unread message

Marc Grue

unread,
Sep 4, 2017, 5:19:24 PM9/4/17
to Lift
Hi alll,

If you don't know of Li Haoyi, (blog, talks, GitHub) he's a very interesting Scala programmer and author of several open source libraries that I can highly recommend to check out.

I got to think of Lift's documentation seeing this talk on open source libraries/communities:


And maybe his Scalatex doc generator library could be a tool to build the documentation with?:


Cheers,
Marc

Matt Farmer

unread,
Sep 12, 2017, 10:37:21 PM9/12/17
to Lift
Thanks for shooting this over Marc. Sorry it took a minute to get a response.

I, too, am interested in seeing us make some changes to the Lift Docs. I'm generally pretty skeptical of the way our Docs are scattered about between Assembla, the Cookbook, Simply Lift, etc. I'm slowly becoming of the opinion that we should totally junk Assembla and have one canonical source of truth for docs that lives alongside the repo. Antonio has some outstanding work for a PR that will do a tutorial in the repo.

I did some scanning of this tool. It looks like it could be an opportunity to do something like make sure our code examples compile (a la dexy) but I'm not sure.

Curious to hear other thoughts.

--
--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

---
You received this message because you are subscribed to the Google Groups "Lift" group.
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Antonio Salazar Cardozo

unread,
Sep 13, 2017, 11:51:35 AM9/13/17
to Lift
I did read through this and didn't have a chance to respond, thanks for bumping it Matt!

A very simple version of my thoughts: our documentation tools are not our problem, our
documentation is. Anything we shoot for above and beyond improved/more easily found
documentation is probably burning time that could be dedicated to writing improved/more
easily found documentation.

That said, when considering tools I personally have two strong preferences:

 - Expressible and readable in plain text (markdown, asciidoc, probably others). I want to
   write documentation, not HTML.
 - Renderable directly in Github.

These two preferences are centered around minimum friction of creation, and maximum
ease of access.

I've also experimented with compilable docs, in a sense, here. It's not a full harness for
extracting code into tests, but it's probably not too hard to generalize into one. Generally
I find that trying to fully integrate docs into code (see literate coffeescript), or tests into
docs (see specs2's “english” non-unit specifications), results in noisy docs and noisy
code. Of course, Donald Knuth would likely disagree, but he also wrote his own language
and basically development process to do literate programming the way he envisioned it :)

Ultimately dexy was an experiment in a way to orchestrate the process of building docs,
extracting tests from them, etc. I would say that today, it makes more sense to just use sbt
to do that rather than introducing more tooling noise. The only dexy stuff in the repo right
now is the basic hookup of the above test extraction/verification, as well as a hookup to
take asciidoc files in docs/ and compile them into the target/docs/ directory for distribution.
We never attached these to our build/release process, however.

All of this is mostly digression. If someone wants to contribute documentation, I would
suggest asciidoc or markdown. They're easy to write and directly supported in Github, and
they're well-understood. Asciidoc is, under the covers, based on the many years of work on
documentation structures and layout that went into Docbook, which is used for documenting
KDE, GNOME, the Linux kernel, and other storied open source projects. It's unlikely (though
not impossible!) we'll run into something we need to do from a documentation perspective that
we can't do with it + scaladoc.

I think Scalateχ is interesting, and I think Li Haoyi's work in general is pretty stellar (indeed,
humbling), but I don't personally see any serious value to writing docs in that format over the
others at our disposal, for our project, at this moment. I would say at worst it's letting the new
shiny distract us from the real work, and at best it's letting the perfect be the enemy of the good.
Thanks,
Antonio
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+unsubscribe@googlegroups.com.

Marc Grue

unread,
Sep 13, 2017, 4:29:08 PM9/13/17
to Lift
Hi Matt and Antonio,

Thanks for your responses. Unfortunately my own time is very limited to help out writing some documentation and I'm also the one in need of reading it :) I hope some more experienced Lifters step forward at some point.

I think Matt is right about having one source of truth, also to avoid having moving (or non-moving) parts getting out of sync with each other.

What I liked with Scalatex is that you can easily point to the raw code without intruding that code with markers (as I have understood it). So, the raw tests that exist in the framework could be referenced directly, and there would be certainty that the examples are always up-to-date since otherwise, the framework tests wouldn't have passed - the bare metal is referenced. And without intruding the source code like scaladocs/others do by writing the documentation inside the code which I have always found a bit hmmm. A helping note here and there, fine. But Scala docs all over, hmmm. Maybe I have just not learned to use it right.

On the other hand I also agree with Antonio that it should be easy and straightforward to write documentation. Maybe the above point (about "intrusive documentation" in the code) and work to sync back and forth is maybe in the end more of a burden than the advantages of Scalatax - I really don't know. A simple test of an "eco-system" might give clues to that. It's more fun to write documentation if the tools are cool too, me thinks :-) And the more fun, the more likely that it gets written.

Just my 2 cents

Thanks,
Marc

j...@joescii.com

unread,
Sep 25, 2017, 10:59:54 AM9/25/17
to Lift
Marc,

Lack of documentation is indeed one of Lift's greatest weaknesses. Fortunately, the community which serves as the primary source of truth is quite stellar. Producing and maintaining documentation is a rather costly endeavor, and thus far no one who has wanted fantastic documentation for Lift has been able to afford it. Most OSS projects which have great documentation have the financial support of a revenue-generating organization, typically in the form of a corporation. 

The second problem is something you hinted at regarding the expertise to write the documentation. Anyone who is proficient with a software tool is going to be more valuable using that tool to solve business problems than producing documentation. Without some source of revenue to employ the experts to write documentation, our most cost-effective way to help ppl is to stay active as possible in the Lift community and assist when documentation is lacking.

The only other way I could imagine Lift getting documentation on par with corporate-backed OSS projects is if we somehow enjoyed an increase in interest. I wasn't part of the Lift community when activity was at its peak, but there is a lot of documentation that was produced during that active period. Sadly regardless of how good a tool is, interest and activity tend to follow trends and shiny new stuff. Given that Lift is a very mature tool it's highly unlikely to catch fire again. It's seems to be one way psychological/sociological forces outweigh technical merits. 

Anyway, big digression... As Antonio pointed out, it's not a lack of tooling which makes Lift's documentation sub-optimal as much as it is a lack of investment into that particular aspect of the project. The ppl who need documentation can't produce it nor can afford to pay capable authors. We all love Lift and wish it could have world class everything including documentation. But as things stand today, our most cost-effective way of serving those who need documentation is to deliver friendly guidance to anyone who asks for assistance.

Joe

Antonio Salazar Cardozo

unread,
Sep 25, 2017, 2:57:25 PM9/25/17
to Lift
On Monday, September 25, 2017 at 10:59:54 AM UTC-4, j...@joescii.com wrote:
Given that Lift is a very mature tool it's highly unlikely to catch fire again.

I don't know that I agree there, fwiw. Lift has a big thing going for it that is slowly but surely
becoming a value driver: security. But getting the word out is another matter :)
Thanks,
Antonio

Marc Grue

unread,
Sep 26, 2017, 7:46:38 AM9/26/17
to lif...@googlegroups.com
Hi Joe,

Thanks for your input! I think this is a very precise description of the current situation regarding community/documentation.

Cheers,
Marc

--
--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

---
You received this message because you are subscribed to a topic in the Google Groups "Lift" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/liftweb/8wyFHy7aNtM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to liftweb+u...@googlegroups.com.

Chris Hagan

unread,
Jan 14, 2019, 10:28:26 PM1/14/19
to Lift
Folks, I'm introducing Lift to yet another corporate environment and I've got some resources, time and energy to adapt the materials I'm putting together to train my team for general usage.

I just need a way in. What's our current best location for:
1) A high level onboarding that includes best practices like data-lift tags
2) A set of strategies and practices like how to separate class names between lift binding anchors and designer style expressions
3) A deep dive into Wizard, LiftScreen and Field structure and extension

These are all resources I'm building/have built. Some of them clearly fit neatly into missing sections of the Lift Cookbook, some of them seem to be edits to other documents.

I'm happy to express them in markdown. Can anyone chime in as to where I can fit them and how I can obtain the necessary access, please? I've been waiting a long time to be able to do this!

Richard Dallaway

unread,
Jan 15, 2019, 5:07:03 AM1/15/19
to jie.lin via Lift
Hello - if you’re keen to add to the Cookbook, the source is in asciidoc (which is pretty similar to markdown). Fork, and PR as you need from: https://github.com/d6y/lift-cookbook 

Happy answer questions.

Cheers
Richard


--
--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

---
You received this message because you are subscribed to the Google Groups "Lift" group.
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+u...@googlegroups.com.

Chris Hagan

unread,
Jan 15, 2019, 6:56:25 PM1/15/19
to Lift
Thanks.  Will do.

c

Matt Farmer

unread,
Jan 23, 2019, 11:09:30 PM1/23/19
to Lift
Updates to simply lift could also be good. It hasn't been updated since 2013 and our conventions have changed a bit since then.


Thanks for being willing to help!

Chris Hagan

unread,
Jan 23, 2019, 11:15:00 PM1/23/19
to lif...@googlegroups.com
Brilliant. Absolutely delighted to. I'll walk through simply lift too. The cookbook is actually fairly up to date, I think I have been thinking of simply lift when I remember the references to the old bindings etc. 

Chris Hagan

unread,
Jan 25, 2019, 7:49:10 PM1/25/19
to Lift
I've got a PR for the first 4 chapters of Simply Lift up now, updated to Lift 3.3.0.  About to take on Screens and Wizards which I think is going to be a pretty big job.

It's using Lyx.  Does anyone have any experience in editing this content?  My totally naive installation doesn't seem happy to produce the PDF of the book so I'm just crossing my fingers and editing the content in Emacs.
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

---
You received this message because you are subscribed to the Google Groups "Lift" group.
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+unsubscribe@googlegroups.com.

Antonio Salazar Cardozo

unread,
Feb 2, 2019, 8:00:30 PM2/2/19
to Lift
Oh wow, it is using LyX isn't it! I might try and see if I can dig in a little bit... The
LyX version used for these is quite outdated, so that could be complicating things.
I wonder if there's a conversion step that needs to happen that the UI does automatically
but the Makefile doesn't?

One does wonder if it makes sense to pipe through pandoc or something to convert
to asciidoc, for example. 
Thanks,
Anotnio

Chris Hagan

unread,
Feb 3, 2019, 7:08:35 PM2/3/19
to Lift
That'd be good. Any help would be welcome on the pipeline.

I'm assuming that the end result needs to be publishable as a pdf or as html. Im not sure whether it has a hard copy publishing path as well?

I don't want to try to unmake any prior decisions. But if there happen to be different constraints in play than there were initially I'd like to get a read on those.

Additionally, and crucially, I don't want to try to coopt anyone who has an ownership of this material. But I'm willing to step into a primary role and if I were to do so I'd need to understand the pipeline deeply, potentially even to the point of porting the content.

But not as a reactive "I can't get this to work" step.

Long story short, any help on the lyx pipeline welcome ;)

Antonio Salazar Cardozo

unread,
Feb 8, 2019, 2:55:34 PM2/8/19
to Lift
Haha yeah. David owned the material but doesn't have a lot of time these days… To me,
it would be interesting to port it to some other system, but not *crucial*, unless it's significantly
blocking. I also think it's probably fine if we can't generate a PDF at this juncture; the HTML
is probably more important.

To which end, it kind of feels like if you have something that works for the HTML version
but doesn't work for the PDF version, it's worth opening a PR and then figuring out the PDF
piece as an independent thing.
Thanks,
Antonio

Henrik Härkönen

unread,
Jun 18, 2020, 4:56:02 PM6/18/20
to Lift
Hello!

Just recently changed my priorities when mentally ranking software, especially web frameworks. I think the best is simply the one with best documentation. And now I'd like to help Lift become that best one! :D

So, wondering, have thoughts solidified on this "one place to rule them all", regarding docs? :D I think having them inside the official main repo would be great.

2 cents about tools. I've always enjoyed reading docs hosted by https://readthedocs.org/ It's just beautiful. That would mean reStructuredText (.rst) and Sphinx I guess for the format. I think people have successfully translated lyx docs into rst, with relatively sane amount of manual labor. It's free and they support git webhooks and even custom subdomains.

Thoughts?

Matt Farmer

unread,
Jun 19, 2020, 8:05:54 PM6/19/20
to Lift
I don't think we've made much action. Antonio started on some work on documentation in the repo.

I've been a fan of readthedocs documentation as well, but we've already got some asciidoc and markdown floating around. I'm a bit apprehensive about adding yet another documentation format? :/

If we did a Jekyll based site on GitHub pages or Telegram site (hi dpp) we could do the same with Markdown and asciidoc right?

Henrik Härkönen

unread,
Jun 20, 2020, 4:07:46 AM6/20/20
to Lift
Yes of course if there is already stuff going on with other formats, let's not saturate it soo much anymore. But I think the main point is to have one central place for comprehensive set of docs and then generating from that is another story. A static generated page on GitHub sounds good to me.

There has been discussions what suits what best, but in the end, I guess it's more important to just pick some and start cranking? :D

-Henrik
Reply all
Reply to author
Forward
0 new messages