Detailed installation instructions for all platforms -- volunteers needed about kons-9 HOT 37 OPEN

https://github.com/kaveh808/kons-9/files/10024972/krma.documentation.pdf

@awolven, I'm reading through it again this morning. I'll offer a few observations here.

I think the most constructive things I can offer now are general suggestions--the kind of thing that a more formal process would call "document-design edits." An orthodox approach would be to come to consensus on the gross organization of the subject matter--the document design--and then fill in the sections until the main topics are covered, and then do style and mechanical edits.

(A "style" edit means things like fixing awkward constructions, observing consistent conventions in different parts of the document, and that sort of thing. A "mechanical edit" means finding and correcting all the typos, punctuation and grammatical errors, erroneous word choices, and so forth that are always in every document.)

You're going to get readers who look at the document because they want to know what krma is and why they should care about it. A short overview or introduction right at the start will help them. Just briefly say what krma is and what's significant about it.

At 45 pages, it's long enough to benefit from a table of contents that lists the major sections. That'll help the first-time reader start with a sense of the size and organization of the document, and help returning readers find specific sections they're looking for.

That's less needed if you choose to break the API reference out into a separate document (more about that below).

The initial "Getting krma installed" section is, as you say, pretty rough. It's a good thing to put in the document, but the current version is pretty incomplete.

An install section should say what platforms it supports and should provide a complete, clear, step-by-step process for each supported platform. The steps should include listing any prerequisite installs, along with links to the relevant downloads and the install instructions for them. If a prerequisite is needed and there's no useful step-by-step install document for it, then we should provide those steps in our document.

We should write the instructions so that an intelligent person can start at step one and, with no prior experience with krma or the rest of kons-9, can reasonably expect to have a working install on whatever supported platform they're using when they complete the last step.

It's a bunch of drudgery to cover all the needed steps of an install for all supported platforms, but that's just the nature of this kind of document.

The list of implemented calls amounts to an API reference, and would benefit from being clearly organized like one. You might even consider breaking it out into a separate document called something like "krma API Reference."

The simplest thing you can do to help a reader is to alphabetize the entries; that makes it much easier to find something that you're looking for.

You might argue that it's better to group related APIs together, and you're not wrong, but if you're going to do that, the doc would benefit from dividing the reference into sections with one section for each set of related APIs, and a heading and brief introductory paragraph or two that explains what each set of APIs is about.

It'll still be helpful to alphabetize entries within a section, and an alphabetical index of all APIs is even more helpful. That's a bunch more work, of course.

from kons-9.

For the kind of documentation we want to write here, I generally appreciate the FreeBSD Handbook as an example. It is widely available, detailed but terse and most of the time sets clearly the audience and the outcome expectations at the top of the document. This can be seen for entry level documentation or most advanced documentation:

• https://docs.freebsd.org/en/books/handbook/basics/
• https://docs.freebsd.org/en/books/handbook/jails/

Good advices I have received as a mathematician on how to write or talk is to assume people know nearly nothing but are infinitely intelligent. One of the consequence of the premise is to always good context for people to do their research, even if this context is just captured by a single word or expression. Another consequence is to always provide one explanation, but that it's actually not always useful to provide additional different explanations, additional explanations tend to be confusing. (There is also pedagogical research about that.)

Regarding style, I have compiled the most useful advises I received as a non-native speaker on this pag: https://www.melusina.org/consulting/2021/09/23/improving-written-and-verbal-communication-in-english.html#post-title , for what it's worth.

P.S.: I'm happy to read and contribute when I have a bit of time again.

from kons-9.

It's probably a good idea to write the per-platform instructions out first, even if we're going to try to automate it. For one thing, working out and documenting the right steps is a good first step toward automating them.

I'll write instructions for all three platforms if I can get someone to review them for each platform. Alternatively, if someone else wants to write them for one or more platforms, I'll review them.

It would be nice to maintain a common structure and style in all three sets of instructions for the benefit of readers.

In addition, we might want to add a HOWTO describing how to get started implementing something simple on top of kons-9. I wrote a simple 2D pond-life simulation years ago in Macintosh Common Lisp (based on an even earlier extension of Conway's life I wrote for Commodore 64); I was thinking of extending Kaveh's boid demo to implement a 3D version of that simulation. Assuming I can carve out time to get it working, maybe I could also write down how I get it working and turn that into a HOWTO.

from kons-9.

I can take Mac OS-X / MacPorts, since this is what I am using.

from kons-9.

In order to produce instructions for all three platforms with a common style and organization, I intend to organize them all the same way. I'm posting the planned organization in case @foretspaisibles or anyone else gets something written before I do, in hopes that we can nevertheless wind up with consistent content and style.

Feel free to push back on aspects of the proposed organization that you find unfortunate.

I. Prerequisites

This section describes the target platform for the install, including any supporting tools and assets that should be installed and configured before we start. For each needed prerequisite that must be installed and configured, we provide a link to instructions for doing so, or, if we can't find such a link, then we write out those instructions inline and ste-by-step fashion.

II. Installation and configuration

This section assumes that all prerequisites are installed and configured. It describes the sequence of steps needed to install kons-9 on the target system and configure anything that needs to be configured for it to work properly, including any supporting editor configuration or what have you.

III. Smoketest

This section assumes that the installation and configuration of kons-9 has been done, and describes in step-by-step fashion how to conduct a simple smoketest that shows the system working as intended, and that illustrates the basics of working with it to help new user get started.

IV. Contacts and avenues of help

This section presents some contact information that new users can use to get help when things go wrong, report bugs and misfeatures, and join the conversation about the use of kons-9.

from kons-9.

What about a script just doing that? We could ask a couple of questions like “do you prefer Brew over MacPorts etc.” and just go for it? Is a good final step “loading demo.lisp” ?

from kons-9.

@mikelevins I like both ideas. If you can, please write the instructions for all three platforms.

As for the HOWTO, I think that is a great idea. I have been writing the various demos as illustrations that people can build on.

from kons-9.

@mikelevins I like both ideas. If you can, please write the instructions for all three platforms.

As for the HOWTO, I think that is a great idea. I have been writing the various demos as illustrations that people can build on.

Great; will do. I may poke you with questions about the boids demo.

from kons-9.

I can take Mac OS-X / MacPorts, since this is what I am using.

Maybe we should coordinate. I was planning to write MacOS instructions first, because that's my default dev system, though I also have Windows and Linux dev machines.

You could write and I could edit, or I could write and you could edit, and then I (or another volunteer) can write the Linux and Windows instructions, conforming to the same general style.

If you have a preference, or if you get a draft written before I do, let me know. Otherwise, I'll let you know when I have a draft ready for your review.

from kons-9.

One thing which would help is just explaining each step, and offering a sensible default, or explaining why one can't use a default --- I was blocked on the Windows version loading in script mode and not having available the module for dealing w/ file paths.

from kons-9.

One thing which would help is just explaining each step, and offering a sensible default, or explaining why one can't use a default --- I was blocked on the Windows version loading in script mode and not having available the module for dealing w/ file paths.

Thanks; that's good advice.

I'll try to write the instructions step-by-step, including every necessary step, just as I approach similar things when working as a tech writer. I encourage other authors to do the same.

You and others can help us get this right by trying to follow our instructions exactly as given, and complaining to us when you're blocked.

from kons-9.

This is my attempt. Please feel free to criticise me, offer suggestions, or say anything relevant.

https://github.com/bigos/kons-9-notes/blob/main/detailed-installation-instructions/Linux.org

from kons-9.

This is my attempt. Please feel free to criticise me, offer suggestions, or say anything relevant.

https://github.com/bigos/kons-9-notes/blob/main/detailed-installation-instructions/Linux.org

Thanks for your quick draft.

I read it, followed it on a local Ubuntu system that did not have kons-9 on it, and rewrote the starting sections to be more in line with the style I had in mind. You can find my rewrite here:

https://github.com/kaveh808/kons-9/tree/mikelevins-draft-instructions-linux/doc

in the file install-linux.md. Please push back on any mistakes or other things you don't like. That goes for all contributors.

When and if that file meets with general approval, we can fill out the rest of the instructions. We can then use it as a template for writing the instructions for macOS and Windows, too.

The objective is to wind up with three install-* files that have the same style and feel, so that anyone who has used one of them will feel at home with either of the others. Anywhere they need to differ because the platforms differ, they will, but otherwise they should read pretty much the same.

from kons-9.

@mikelevins I have plagiarised your work with some modifications. Does anything worth plagiarising back stand out?

from kons-9.

One thing which would help is just explaining each step, and offering a sensible default, or explaining why one can't use a default --- I was blocked on the Windows version loading in script mode and not having available the module for dealing w/ file paths.

I had success on Windows because I had installed msys2.
https://www.msys2.org/

from kons-9.

https://github.com/bigos/kons-9-notes/blob/main/detailed-installation-instructions/Windows.org

This is my go at Windows instructions.

I wonder if someone can have suggestions to fix the problem of an uncomfortable sbcl path.

from kons-9.

We're getting there. I have a full day today, but I'll make another pass on the Linux instructions and tackle a rewrite of the Windows version as soon as I can.

There are a number of standard tech-writing things we can do to get an improved result. I don't want to turn this comment into a tome about tech writing, but I'll offer one example, to give you the idea of the kind of thing I mean.

A standard rule in tech writing is that you don't describe the effect of an instruction using a construction like "this will do that." For example, you don't say, "git clone will download the repo." Instead, you say "git clone downloads the repo."

The reason is that the future-tense construction is ambiguous. It might mean "git clone downloads the repo," or it might mean "a future version of git clone will one day download the repo." It may seem obvious which one you mean when you write it, but it's much less obvious to readers following instructions. To avoid ambiguity and the confusion it can cause, the standard style is to always use present tense active indicative to describe what happens when you follow an instruction.

There are a ton of details like that. I'll fix them up in editing and rewriting. I will make mistakes, and I encourage other contributors with an editor's way of looking at things to correct my drafts, too.

from kons-9.

A good way to learn writing style is to study and imitate the best, preferably professionally copy edited. ("Inside MacIntosh" and "Inventor Mentor" come to mind for technical writing. Wernecke is an amazing writer.) I learned this after asking a writer once, "Do I put the period before or after the closing quote?"

I like Inside Macintosh too, though I'm biased. I started my Silicon Valley career working as a tech writer in Apple's tech pubs department, the same people who wrote and published Inside Macintosh. That's where I learned the craft of technical writing and the style and rules I habitually observe are derived from Apple's house style.

from kons-9.

from kons-9.

mikel, maybe you could critique the krma documentation https://github.com/kaveh808/kons-9/files/10024972/krma.documentation.pdf It's pretty rough right now.

I'm happy to look at it, but you'll have to be patient; there are several things competing for my attention right now, and I'm behind on a couple of them. I'm also rather forgetful, so you'll probably need to remind me, maybe more than once.

Do you know how to read editor's marks? If not, here's a cheat sheet:

https://amstp.northwestern.edu/documents/proofreading-marks-at-a-glance.pdf

from kons-9.

Apple hasn't been shy about publishing it's style recommendations--I wonder if any of their standards for tech writing are published on-line. They do have some of the Inside Macintosh books on their dev site.

They have a style guide online, but I wouldn't try to learn technical writing from it. It's more intended for people who are already tech writers, and who want to know how to make their work sound like Apple.

For what it's worth, here it is:

https://help.apple.com/pdf/applestyleguide/en_US/apple-style-guide.pdf

They do reference The Chicago Manual of Style as a reference for style and usage. That's a large, expensive resource, but a good one. I always have a recent edition on my bookshelf.

If you want a more compact reference covering a lot of the same things, check out Words into Type, which Apple also uses.

You won't get all of their style from reading any book, including their style manual. Apple maintains a publications department (or used to, anyway) with professional writers, editors, indexers, book designers, and so on, and much of the house style is contained in the heads of those people.

from kons-9.

The Elements of Style is still great.

from kons-9.

Thanks for the feedback and recommendations @mikelevins. Very well thought out.

I especially agree with the step by step installation guide. We need to make it easy to try out karma with kons-9. I know it's something that always trips me up. Still trying to wrap my head around the interactions of Git, Quicklisp, and asdf.

Maybe as a starting point @lukego could write up the steps he took to get karma running on Linux?

from kons-9.

Thanks for the feedback and recommendations @mikelevins. Very well thought out.

I especially agree with the step by step installation guide. We need to make it easy to try out karma with kons-9. I know it's something that always trips me up. Still trying to wrap my head around the interactions of Git, Quicklisp, and asdf.

Maybe as a starting point @lukego could write up the steps he took to get karma running on Linux?

I'm also on the hook for new drafts of the step-by-step kons-9 install instructions. I know it's taking me a long time; bear with me. They're coming. And thanks to the other contributors who've pitched in.

from kons-9.

I appreciate everyone's help in this volunteer effort. And I am taking the long view. Please don't feel rushed.

from kons-9.

from kons-9.

mikel, Thanks for moving forward with this. I will break out the API reference from the rest of the document. What do you think of breaking out the installation instructions from the architecture description? Right now there needs to be work done on the actual code. I may add an extra argument to most api functions, I may add another "flavor" of draw call to the existing three. Glaring usability concerns need to be addressed and then I can edit/rework the sections between the installation instructions and the API reference.
…
-AKW
On Wed, Nov 23, 2022 at 1:50 PM mikel evins @.> wrote: Thanks for the feedback and recommendations @mikelevins https://github.com/mikelevins. Very well thought out. I especially agree with the step by step installation guide. We need to make it easy to try out karma with kons-9. I know it's something that always trips me up. Still trying to wrap my head around the interactions of Git, Quicklisp, and asdf. Maybe as a starting point @lukego https://github.com/lukego could write up the steps he took to get karma running on Linux? I'm also on the hook for new drafts of the step-by-step kons-9 install instructions. I know it's taking me a long time; bear with me. They're coming. And thanks to the other controbutors who've pitched in. — Reply to this email directly, view it on GitHub <#175 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABGMMKPU7MHYCVGJAW2OMLWJZYQLANCNFSM6AAAAAAR47RPIQ . You are receiving this because you were mentioned.Message ID: @.>

I like the idea of separating installation from other content. Good installation instructions tend to be pretty long, and breaking them out into a separate document will make the introductory document more approachable.

It might be helpful to give the intro document a name like "Introduction" or "Overview", and include in it a brief description of what the other documents are. Readers are likely to start with the introduction, and that gives you th opportunity to explain the purpose of all of the documents, which will help them find particulars that they're interested in.

Another thing you could do is keep the documentation for krma in its own subdirectory and name the intro document readme.md, so that when people browse the github repo, clicking into that directory automatically shows the intro with its roadmap of the other documents.

from kons-9.

I'm back at work on the install docs, but I need a little help getting the kons-9 window up on Ubuntu 20.04. The last time I was working on it I was able to use the next-to-last expression at the bottom of kons-9.asd to show the kons-9 window, and then run Kaveh's venerable demos. I had intended to document that approach as a simple smoke test of the install.

When I try it with my install instructions in the current main branch, the Lisp creates a window that immediately disappears and then displays the following error message:

OpenGL Version: 3.1
WARNING: vertex shader failed to compile
Date/time: 2022-12-20-15:58!
An unhandled error condition has been signalled:
0:1(10): error: GLSL 4.10 is not supported. Supported versions are: 1.10, 1.20, 1.30, 1.40, 1.00 ES, and 3.00 ES

It's pretty clear from the message what the actual error is; what's the proper solution? Please bear in mind that I'm documenting in excruciating detail how to go from nothing to a working kons-9, so don't be afraid to hold my hand in equally excruciating detail.

Thanks in advance for help with this. Once I can follow these Linux instructions start to finish and get good results, I'll port them for the other platforms.

from kons-9.

from kons-9.

Mikel, you can either try to get a newer gl context, which requires some keywords to glfw:with-init-window in src/graphics/glfw/glfw-gui.lisp (I would have to look them up.), or you can force your kons-9 to use the opengl2-text.lisp instead of opengl3-text.lisp by changing the #+darwin and #-darwin reader macros in kons-9.asd. I wouldn't put that in the instructions though, we may just change all opengl versions to use opengl2-text.lisp as we're trying to make vulkan the default now.

Hmm...it sounds like there's not a really good way to give a precise and reliable step-by-step right now. Is that accurate? Perhaps I should wait until this work settles down, and then complete the instructions? I hate to write a HOWTO that doesn't really tell a reader how to.

I assume you mean that Vulkan will become the default on all platforms, so maybe it's better to let all that shake out, and then write the instructions to reflect the use of Vulkan (including instructions on how to get and install Vulkan itself).

But if there's a stopgap document that seems useful to you or @kaveh808 let me know and I'll work on it.

from kons-9.

from kons-9.

from kons-9.

from kons-9.

I guess I'll just have to fiddle with it. If I get kons-9 working on Ubuntu again, I'll document it.

For reference, in case anyone cares to advise me further, I'm trying to get it running again on Ubuntu 20.04 on an Intel i5 with Intel UHD graphics, on sbcl 2.27.

from kons-9.

I would suggest waiting on the Vulkan version, as the OpenGL version will be phased out over time. I don't want @mikelevins to do work which has a limited shelf life.

from kons-9.

I would suggest waiting on the Vulkan version, as the OpenGL version will be phased out over time. I don't want @mikelevins to do work which has a limited shelf life.

Understood. I'll defer work on the install docs until you think it's time. Meanwhile, I'll tinker with kons-9 for my own purposes, and if I make something that seems interesting, I'll let you know.

Also, if there are other things I can help with, let me know.

from kons-9.

Cool, thanks. @awolven has the Vulkan code ready to merge with the kons-9 main branch. Need to figure out how and who will do that along with the installation instructions.

from kons-9.