search

CasparCG / help

File an issue here if you need help with CasparCG by the community-led support :+1:
https://casparcg.com
74 stars 8 forks source link

Update Wiki for 2.2 #13

Open Julusian opened 6 years ago

Julusian commented 6 years ago

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 commented 6 years ago

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

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?

dotarmin commented 6 years ago

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 commented 6 years ago

Do you mean Gitbook or Github Pages?

dotarmin commented 6 years ago

I mean Gitbook :)

silid commented 6 years ago

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

olzzon commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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.

mint-dewit commented 5 years ago

we need to do something quick about the wiki.

This was 1,5 months ago...

Looked at GitBook real quickly, seems like it supports multiple versions out of the box, is free for open source projects and can sync with GitHub. I see no reason not to use this. Can @dotarmin just set up an account there and distribute access?

Regarding HTML, someone has written a nice post about this on Medium:

We should at least link to these.

dotarmin commented 5 years ago

Hi @baltedewit,

I have been exploring a new structure for the wiki and it's starting to take shape. Plain file structure with a clear naming convention for files without unnecessary folders which makes it easy to maintain and find appropriate files when wiki has been cloned.

However, the drawback with this solution is that it can be hard to maintain the custom sidebar. I'm thinking of the links. I have started to figure out a smart way for this but I'm not there yet.

Can @dotarmin just set up an account there and distribute access?

I have explored Gitbook before and liked it. What I didn't like was the fact it's "outside" GitHub if you understand. I have to setup a CasparCG organization on GitBook first and apply for the open source discount before I can do anything more in GitBook.

I will write a comment when it's done and more community members can help evaluate GitBook.

/Armin

mint-dewit commented 5 years ago

I have been exploring a new structure for the wiki and it's starting to take shape

Well, put it up in a branch and let's work on it together! This is a real problem that urgently needs a solution. I'm sure that if we make an effort as a community that we can have something that works for all of us in a few weeks.

dotarmin commented 5 years ago

@baltedewit after exploring GitBook again I have to say it has improved since I checked it last. I really think we should strive for going that way? I have created a CasparCG organization at GitBook and applied for a plan because we're an open source project.

Currently I cannot invite any members until we get the open source plan approved.

dotarmin commented 5 years ago

The CasparCG project has now received a free plan for open source project at GitBook 📖 ❤️ . I will start to contact community members and invite users to GitBook during this week. Before we do any documentation we should have a chat on Slack or something regarding how to structure the documentation. I will put together a group for this conversation.

Any thoughts so far?

mint-dewit commented 5 years ago

Awesome!

I made a scratch of what intuitively makes sense to me as a structure:

Guides
    Getting Started (should be a hello world, rather than an install guide)
    Template development
        HTML
        FLASH
        SCENE (legacy)
    Client development

Configuration
    Config File
    Vision mixer settings

Producers
    HTML
    FFMPEG
    FLASH
    IMAGE
    COLOUR
    DECKLINK
    SCENE / PSD (legacy)
    FRAMERATE (legacy)
    ROUTE

Mixer

Consumers
    BLUEFISH
    DECKLINK
    FFMPEG
    IMAGE
    NEWTEK
    SCREEN

Related Projects
    libraries
    templates
    clients
    tools

Diagnostics

Supported Hardware
    Minimum Requirements
    Recommended system
    Supported capture cards

Protocols
    AMCP
    OSC
rf152 commented 4 years ago

Is the gitbook live? I can't seem to find it. I'm keen to use CasparCG, but at the moment I'm struggling with the lack of documentation, especially around AMCP and OSC integrations.