search

LMS-Community / lms-community.github.io

This is the web page for the Lyrion Music Server Community repository
http://lyrion.org/
25 stars 19 forks source link

Proposal to use the Issues functionality here to track migration of legacy LMS embedded Help pages #26

Open Daksol opened 2 months ago

Daksol commented 2 months ago

Recent discussion in forums indicates that we should be planning to migrate the HTML Help pages which were embedded in the LMS distribution to this new Lyrion.org repository.

These pages linked on any LMS install via base url: http://lms-server:LMSPORT/html/docs/

There are about 15 of these pages, excluding menus, of which one has been done.

The content of each page does need a bit of thought:

So proposal (following up other discussions with @lauret etc) is:-

This will generate a few issues; on other hand the discussions should be short and easy to follow.

Hope this sounds ok. Respond asap if not!

HELP MENU

TECHNICAL INFORMATION MENU

michaelherger commented 2 months ago

Excellent initiative! I've created a project at the org level: https://github.com/orgs/LMS-Community/projects/2/views/1. Can you access that? Please add all the issues you create to that project. As it's not limited to this repository it also allows us to create issues on slimserver to remember to clean up the links etc.

Daksol commented 2 months ago

Link you have provided gives me a 404 error.

I can see https://github.com/orgs/LMS-Community/projects

But this shows only a single project, The Great Renaming Project.

(I had created a couple of HTML doc migration issues here just to indicate what I was suggesting. Once I get access to your new project I will close the issues here and recreate them in that location).

michaelherger commented 2 months ago

You should have received an invite by now. And no need to close these issues: they can be assigned to the project!

Daksol commented 2 months ago

Yes I have access now. And I see that the issues created here (LMS-Community/lms-community.github.io) are showing there,

One more small info. Not familiar with this Github project mechanism. What option does one use to create an item in the Project directly?

michaelherger commented 2 months ago

Haven't used this before, either... It's a relatively new feature on Github.

https://docs.github.com/en/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project

At the bottom of the columns there's an 'Add Item' button. Those items later can be converted to issues in the various repositories.

Daksol commented 2 months ago

Not seeing an Add item button so far on the Projects page.

michaelherger commented 2 months ago

You have to accept the invite you received.

Daksol commented 2 months ago

Invite accepted, pages refreshed. Sorry, still not seeing the add button.

michaelherger commented 2 months ago

You had to accept the invite before I was able to add you to the project. Which I now did. Better?

Daksol commented 2 months ago

Got it now!! thanks.

Daksol commented 2 months ago

It is very joined up. I created a new item in the Project for the Remote Control reference page.

I then allocated it to a Repository (lms-community.github.io )

And it (magically) created an Issue here in the lms-community.github.io repository.

That is probably the right way round to do things - because there will be issues raised in the lms-community.github.io repository which will NOT necessarily be part of the documentation cleanup project.

terual commented 2 months ago

Nice work @Daksol!

Daksol commented 2 months ago

@terual @mherger I have now created an Issue for each of the unmigrated pages in the legacy HTML docs.

Some already have been assigned and moved to the in progress category.

However there remain a few which (IMHO) need people with much deeper knowledge to check before they get worked on.

Could I ask that you open these issues and add a comment to confirm that the migration proposed is ok etc.

Thanks

@terual - I think these two can be merged into material you already migrated

@mherger

Could you make a quick comment into each of these in order to confirm that the material is appropriate to migrate

This one is labelled as being out of date. What to do with this page? Have a special "obsolete information" section?

Daksol commented 2 months ago

Proposal for handling material from this /docs/html area we are not going to migrate.

We now have an Issue for each chunk of not-migrated content which is documenting the decision not to migrate. And that Issue would be a good place to hang things, so to speak.

So to wrap up such items, something on these lines:-

That would make it pretty easy for any future retro-tech historian to review the backwaters of the technical legacy.

Sound ok?

michaelherger commented 2 months ago

Thanks a ton! I've commented on most of them, but haven't taken any decision or other action yet. What you suggest makes sense. Though I would go with a permalink, rather than copy/paste of content. The link doesn't need to be tied to a release, just whatever is in there before we remove it.

Daksol commented 2 months ago

OK. will do a Permalink as standard. Tho I would suggest the CLI sufficiently complex that it would warrant the actual unmigrated content (as an attached file, not code pasted in).

mherger commented 2 months ago

but why copy content, when a link would point at the exact same? The presentation in the linked document would be infinitely better than when pasted here.

Daksol commented 2 months ago

Take your point wrt most situations - links to LMS v8.5 included.

Thought an exception worth making for the unmigrated sections cli-api.html given that it is 13,000 lines or so, quite an expedition to get one's head around.

Daksol commented 2 months ago

Target locations for migrated material which is not part of the mainstream current generation of kit, protocols etc

Material which is essentially OK, but related to legacy kit etc

Material which is being retained, though needs to be udpated