Very confused by the docs

Question

Hey guys, I just wanted to get started with spectacle, but the docs are confusing me quite a bit. These are the issues i am having:

1. “Getting Started with Development” - this paragraph tells me, that all my source files have to be inside the src/ dir. So far so good. But this also reads a bit like there should already be such a directory after installing spectacle with yarn/npm. I assume spectacle just wants me to create src myself? Edit: My bad - i completely missed the Getting Started section. It might be benefitial to move Getting Started before Basic Concepts.
2. The next part tells me to start a development server with ominous npm-scripts which are not yet part of my package.json. Instead I should look inside examples/js - I realize these are part of the spectacle repository. But how am I supposed to access these just after running yarn add spectacle? Ofcourse I could look inside my node_modules, but is this what you want users to actually do?
3. Is there a way to use spectacle with multiple markdown or even js/jsx files? I can’t seem to find anything inside the docs

Thanks in advance 😃

[kale-stew]

Hi Theo! Thanks for opening this issue. We spent a lot of time rewriting these docs and issues like these help us better understanding where we might have missed our mark. 🙂

1. It seems like our use of the phrase “Getting Started” in two places is confusing. The “Getting Started with Development” paragraph you initially refer to here is about developing against the Spectacle src. I agree, this blurb should probably be moved into a Contributing section or somewhere else, where it’s more obvious that this is about the dev process and not deck creation. If you navigate to “Getting Started” (second from the bottom in the lefthand navigation), you will find the tutorial we wrote to introduce newcomers to the library.

2. By “the next part” are you referring to the “Writing Your Presentation” sub section? We did link to the spectacle-cli repository and documentation directly in this section, but I understand if the link decoration wasn’t obvious at first read. We intended to make it more clear that use of spectacle-cli was just another option for developing with Spectacle, but it sounds like we missed that mark with our phrasing as well. To address the second half of your question here, it sounds like we should once again better indicate that “Getting Started: A Tutorial” will be your better bet for clear, step-by-step instructions, and not the “Basic Concepts” subsections.

3. I don’t believe we have a process documented anywhere for using multiple markdown or jsx files, but I do know we have a couple of open issues surrounding imported slides (#871, #870) so we will need to resolve the existing bugs before we formalize a process around imported slides. I can spend some time on this today.

Hopefully I’ve addressed your concerns here, but please don’t hesitate to ask more clarifying questions. Additionally, I will try to reorg our docs to make them more intuitive to navigate. I’m sure you’re not the only one with these questions. 👍

[on3iro]

@slorber unfortunately I didn’t (if I remember correctly - it’s been a while since I last used spectacle)