Write the damned book

[oubiwann]

There are a handful of phases involved ... and they're not actually linear/sequential, they're more combined + iterative. Which means that, even if a section looks "done" it's actually not. They will be tuned over and over 🙂 So, here are the "phases":

Phase I

• Move useful content out of existing old docs.lfe.io site
• Update that content for LFE 2.0
• Add redirects for moved content from docs.lfe.io to cnbbooks.github.io/lfe-manual/current (note that when officially published, these will redirect further to lfe.io/books/chineual)

Phase II

• Examine each section of the Lisp Machine Manual and carry as much of its good qualities over to the LFE Machine Manual
• Key differences include more information about usage or links to online resources that cover usage in more detail
• Explore the possibility of scraping / parsing Existing Erlang STDLIB and ERTS Reference Manuals and the Erlang User Guide ... but only if a good user experience can be created; otherwise, just link out to these, as applicable

Phase III

• Examine three key Erlang books for content + topics (Erlang Programming, LYSE, Designing for Scalability)
• Carry these over for use in the Chineual chapters
• There are some pre-existing LFE examples and articles which may be pulled in for this as well (blog posts, Rosetta Code, various LFE orgs & repos, etc.)

Phase IV

• Lastly, some of the most competent, useful, and even compelling online manuals / books being produced right now are for Rust
• Examine those Rust resources for inspiration (content to cover, organisation of said content, etc.)
• Pull in as applicable

Note: this is a work in progress, it's not being published to lfe.io/books yet. Drafts are published here: https://cnbbooks.github.io/lfe-manual/current

Primary sources

LFE:

• The minimalist guide that ships with LFE: https://github.com/rvirding/lfe/blob/develop/doc/src/lfe_guide.7.md
• The LFE port of the Erlang Tutorial: https://lfe.io/books/tutorial/
• Any still-useful old content on docs.lfe.io

Erlang:

• Erlang Reference Manual User's Guide: https://erlang.org/doc/reference_manual/users_guide.html
• Kernel Reference Manual: http://erlang.org/doc/apps/kernel/index.html
• Erlang Run-Time System Application (ERTS) Reference Manual: http://erlang.org/doc/apps/erts/index.html
• Learn You Some Erlang: https://learnyousomeerlang.com/content
• Erlang Programming: https://www.oreilly.com/library/view/erlang-programming/9780596803940/
• Designing for Scalability with Erlang/OTP: https://www.oreilly.com/library/view/designing-for-scalability/9781449361556/

Lisp:

• The Lisp Machine Manual: https://drive.google.com/file/d/0B1AjIfhQqXG_Um1sMVh5Ump2R2M/edit
• The Revised Maclisp Manual (The Pitmanual): http://www.maclisp.info/pitmanual/
• Common Lisp HyperSpec: http://www.lispworks.com/documentation/HyperSpec/Front/index.htm

Rust:

• The Rust Programming Language
• The Rust Reference
• Rust by Example

Contributing

If you are interested in contributing to this effort, the most important preparatory steps you can take are:

• read up on the primary resources above
• examine the content that has already been produced
• have a discussion in #docs on the LFE Slack about an area of interest where you'd like to contribute
• spend a few weeks diving into an agreed upon area in Erlang as well as LFE, examining their differences and taking notes on your experiences
• spend a few days examining the Common Lisp analogs
• fork this repo
• write a concise narrative for the topic at hand in the same style as the content already produced
• commit/push to your fork and submit a PR for the content
• work with the editors to make changes according to their requests
• rinse and repeat 😄