Documentation request: How do I incorporate this project?

[alexfornuto]

First off, thanks for this repo! I look forward to being able to use it.

I assumed I could npm install this into my project and import it, is that the case? If so, what's the syntax to import it?

If not, what's the suggested method of implementing this project into a site?

[Garrett-]

I would suggest taking a look at the demo page. It's very simple but should help to demonstrate implementation.

Include the fully compiled CSS file. Include the audio JS file (optional). Then it's a matter of understanding how to use the classes.

[alexfornuto]

Yes, I looked at the demo. This is documentation by example, which is great for those who have done this sort of thing before. Consider documenting this project as if it was the first of it's type people would try to use, as it may inspire someone to learn.

I ended up adding the repo as a submodule, then importing the css file directly from there, but it seems an inelegant solution to something I could also install as an npm package.

[jrwarwick]

I would say instead that this project bears a different kind of elegance. You can download, develop and use this with nothing more than a browser and a text editor! Just download zip distribution, unzip, and open index.html in your browser (as long as you don't have strict no-local filesystem policy). Now you can edit index.html with a simple text editor and reload the page. Very, very lightweight, streamlined, and minimum tools are ubiquitous. And grabbing it from a commandline is really pretty easy, too:

git clone https://github.com/joernweissenborn/lcars.git
  or
curl -LO https://github.com/joernweissenborn/lcars/archive/master.zip
  or
Invoke-WebRequest https://github.com/joernweissenborn/lcars/archive/master.zip -OutFile lcars_framework.zip

There are some plans for more demonstration and template pages, eventually. But I as you suggest, it would be helpful to have a some introductory material to help accommodate people approaching it when it is "first of it's type [they] would try to use" and I certainly do hope that it may inspire people to learn! I will draft up a proposal and perhaps a pull request for it.

I am not well versed in the NodeJS/NPM world. This is a lightweight, pure client-side framework. Would that be an appropriate type of package for npm?

[alexfornuto]

I am not well versed in the NodeJS/NPM world. This is a lightweight, pure client-side framework. Would that be an appropriate type of package for npm?

Maybe? I'm just a technical writer forced to dev his own solutions, both at work and for personal projects. Maybe I'm over-thinking it, and just importing the style sheet is good 'nuff.

Then again, it would also be cool to have React components for common LCARS component configurations that were drop-in usable, but that's a little out of scope for this issue.

Feel free to close, or keep this issue open if you want to use it to track the need for introductory material, as noted above. Thanks again for helping bring my LCARS dreams closer to reality.

[joernweissenborn]

I put some thought into the documentation issue.

The basic idea is, that everything should work like Bootstrap. You import the the CSS file (which is transpiled from stylus code) and add classes to your div etc. So I think we maybe need to extend our Readme and explain this approach better.

If you know bootstrap, then you know how LCARS works. What do you think @jrwarwick ?

[joernweissenborn]

@alexfornuto I am very glad we brought you further in your LCARS dreams, that is why this project was created (besides my own LCARS dreams) :D

[jrwarwick]

I agree completely, @joernweissenborn .
Perhaps also a portion of that explanation can also be copied into the top, introduction section of the example/doc as well.

[dthv]

The demo file's source is in lcars/lcars/index.html, right?

[jrwarwick]

Yes, exactly. It is both documentation and an example at the same time. Kind of also a starter/template; just rip out the stuff you don't want and replace the content of what you do want. Examining the source of index.html should reveal some source comments that will help explain some of the way it works, too. Some time in the future we are probably going to have a few supplemental templates that will illustrate even more.

…

On Sun, Nov 1, 2020 at 7:13 AM dthv ***@***.***> wrote: The demo file's source is in lcars/lcars/index.html, right? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#57 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALAR5FJDOVPNA6W4ED7YXTSNV3KFANCNFSM4TBI4TNQ> .

[jrwarwick]

Perhaps a tangent, but @joernweissenborn , I have noticed that in the demo/doc's html header, there is a style element with a few rules, including making the body background-color: black. My reaction is that it (and perhaps the other rules, too) should go into the Stylus source as well, but perhaps it should not for a reason or scenario I have not thought about. If the latter is the case, this should be included in our documentation and explanation enhancement.

[alexfornuto]

As a tech writer, let me just say I'm very happy to see a project like this have maintainers publicly discussing docs best practices. ❤️

[joernweissenborn]

@alexfornuto Nothing to hide here, we are all here to learn from each other :)

@jrwarwick Yes, at one point it even was in the lcars-app-container class. It is commented out, see here. I don't remember why I did so, maybe I just forgot. One can easily test by (un-)commenting regarding lines, I don't have the tooling installed at the moment, so I can't test myself, but I'll put that on my weekend to do.

[jrwarwick]

I've created a pull request for this issue. To preview:
https://github.com/jrwarwick/lcars/tree/fix-documentation-introductorial
and
https://htmlpreview.github.io/?https://github.com/jrwarwick/lcars/blob/fix-documentation-introductorial/lcars/index.html
@alexfornuto , how can we make it better?

[alexfornuto]

I did a quick read and it looks pretty good! I'm travelling this week, but I'll take a look next week more thoroughly.

[joernweissenborn]

What I always wanted is to add in the docs is some kind of navigation in the elbow. It would make it easier to jump to a specific topic and would also demonstrate use of the elbow as a navigation/tab/whatever bar.

[dthv]

I think that could be actually within reach of my skills. I could do this, but the task would have to wait until end of next week.

[jrwarwick]

@joernweissenborn I put in just 2 such links in my branch, is that what you had in mind? But probably one element for each section? If so, I do have a commit somewhere else (I think in the inputs branch) that adds ID attributes to each h1 tag. Maybe I should push that through first, then this one, then @dthv could file his or her ( sorry, I do not know anything about you) own pull request which replaces the paltry two side menu buttons with a table-of-contents set of buttons.
Are we in agreement, fellows?

[joernweissenborn]

@jrwarwick I don't have dev tools at hand right now, can you post a screenshot of your side menu?

[jrwarwick]

I will do so. However, you can also see it just by following this link:
https://htmlpreview.github.io/?https://github.com/jrwarwick/lcars/blob/fix-documentation-introductorial/lcars/index.html

Notice that it is actually a special webapp that takes a repo url as a parameter and serves it up.

[joernweissenborn]

Nice tool. The menu looks good! Am Do., 26. Nov. 2020 um 02:34 Uhr schrieb Justin Warwick < notifications@github.com>:

…

I will do so. However, you can also see it just by following this link: https://htmlpreview.github.io/?https://github.com/jrwarwick/lcars/blob/fix-documentation-introductorial/lcars/index.html Notice that it is actually a special webapp that takes a repo url as a parameter and serves it up. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#57 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARG7QNM532JE5LQWVAC473SRWWDNANCNFSM4TBI4TNQ> .