New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Wiki for 2.2 #13

Open
Julusian opened this Issue Oct 2, 2018 · 10 comments

Comments

5 participants
@Julusian
Copy link
Member

Julusian commented Oct 2, 2018

The wiki needs to have its content updated for 2.2, as it all is only accurate for 2.0 and so is really outdated and confusing to new users.

A discussion needs to happen on whether to approach this by cloning almost every page, or to split each page/heading into subsections, but I think it crucial we retain anything 2.0 for the time being.

Areas needing work:

I likely missed some pages, I only went down the sidebar and skimmed over the content

@silid

This comment has been minimized.

Copy link

silid commented Oct 2, 2018

We could create folders under server and maintain the wiki pages seperately for each version.
eg.

  • server/2.0/
  • server/2.1/
  • server/2.2/

Although pages can be stored in folders in git (which is how you can have different sidebars in each section), each page must still have a unique name.
So should the server pages be renamed:

Server:-System-Requirements to Server:-2.2:-System-Requirements
Or perhaps the latest version can keep the name without the version number and the deprecated versions have to use the version numbers?

What do you think?

@silid silid self-assigned this Oct 2, 2018

@dotarmin

This comment has been minimized.

Copy link
Member

dotarmin commented Oct 3, 2018

You're absolutely right about this. I have actually been exploring other wiki solutions and to try to find a easy way to have the wiki in sync with changes in the server etc. I have been exploring Gitbook that also can be easily exported to a PDF that can be shipped with each build.

I wish GitHub could update their Wiki-feature, I have started to feel often like it's just bare minimum. That's why I have explored Gitbook as an alternative.

@silid

This comment has been minimized.

Copy link

silid commented Oct 3, 2018

Do you mean Gitbook or Github Pages?

@dotarmin

This comment has been minimized.

Copy link
Member

dotarmin commented Oct 3, 2018

I mean Gitbook :)

@silid

This comment has been minimized.

Copy link

silid commented Oct 3, 2018

Jekyll and Github Pages looks interesting (and is free)
https://jekyllrb.com/docs/github-pages/

@olzzon

This comment has been minimized.

Copy link

olzzon commented Oct 8, 2018

I just started using CasparCG a 2 months ago, and didn't´t know that the ACMP documentation was outdated.
Until a new documentation version is out. Couldn't we put a note on the top of the old one saying: "All commands may not be valid for version newer than 2.0.x"
At least it would have saved me lots of hours :)

@Julusian

This comment has been minimized.

Copy link
Member

Julusian commented Jan 2, 2019

Now that 2.2 is released, we need to do something about this.

I am now thinking that maintaining a separate version for each release would be best. So right now we should have a 2.0, 2.1?, 2.2 and master. When we branch off master for a new version, we should do the same in the wiki.
In the rare scenario that there is an amcp change in a patch release (2.2.0 -> 2.2.1) that should just be a comment/note in the 2.2 docs.

How did the research into other platforms go? Anything look promising enough to try out?

@5opr4ni

This comment has been minimized.

Copy link

5opr4ni commented Jan 2, 2019

Hi

Started to poke around in this a couple of days ago, Started to remove things and added others (INFO command) Just for my self. https://github.com/5opr4ni/help/wiki

/olle

@dotarmin

This comment has been minimized.

Copy link
Member

dotarmin commented Jan 3, 2019

Hi @Julusian

Me and @5opr4ni has been talking about this earlier this week and agreed on that we need to do something quick about the wiki. We came across that I will make an overview of how the wiki should look (information wise) and how we should work with it in the future. I will sync what I came up to with some community members and make a POC. If it feels good I will reorganize the current CasparCG Wiki into the new information architecture. I will have something to share this week.

I am now thinking that maintaining a separate version for each release would be best. So right now we should have a 2.0, 2.1?, 2.2 and master. When we branch off master for a new version, we should do the same in the wiki.

I don't mind having it like this and actually think it would be best solution, but wouldn't this best apply only for the protocols? And not the general texts etc.?

How did the research into other platforms go? Anything look promising enough to try out?

I did look into some other platforms such as Gitbook but we continue to stay on GitHub for now even if the wiki feature could be better on GitHub.

@Julusian

This comment has been minimized.

Copy link
Member

Julusian commented Jan 3, 2019

I don't mind having it like this and actually think it would be best solution, but wouldn't this best apply only for the protocols? And not the general texts etc.?

I think we would need to do this for all the wiki contents, as over time any functionality and available producers etc will change. Even the config file structure will change a bit, so example configs will need versioning also.

I did look into some other platforms such as Gitbook but we continue to stay on GitHub for now even if the wiki feature could be better on GitHub.

There are some tools which can convert a github wiki to pdf, so we could look into using something like that to bundle it up to pdf for releases in future. Im not sure how they will play with the versioning though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment