I agree with Mirko, I don't think we should head down the route of creating a full blown publishing framework or similar.
The issue, at least to my mind, is divided into two main things: - text content (which I consider to include tables, lists, etc.) - graphical content For text content there are quite a few good options out there, we probably just need to conduct a hunt for the main competitors and agree on one that meets most needs. Otoh the main ones are probably: - asciidoc - markdown - doc-book - latex - reStructuredText For graphical content my personal opinion is that the possibilities are simply endless and we should not necessarily be trying to restrict what people may want to use either. For the "compiled" presentation in the end I think the common denominator will always be "a picture" (no other way to express a photo or a logo) and I personally think it is fine. The way of getting at this image is what I think we should be focusing on, so the basic idea would be to have a text representation of the image in version control and at "compile" time create the actual image that is then part of the release. For the "text representation" part there are a lot of possible options, what I have used a lot in the past is for example: - websequencediagrams [1] - draw.io [2] But since there are so many services out there that offer something similar I think this should really be something extensible so that people can develop converters for their own formats. For the Apache training content we should then probably have a rule that only converters that are part of the official repo may be used for content, which allows us to curate a little. So basically in version control slides might then look like this: == Slide One * Foo * Bar * World == Slide Two >>> imageContent(websequencediagram) User->Server: Connect Server->User: Respond <<< Whereas the content of the wsd part would be replaced by the corresponding picture when building the actual slides. Hope that made a little sense? Otherwise I am happy to elaborate further :) Best regards, Sönke [1] https://www.websequencediagrams.com/ [2] https://www.draw.io/ On Mon, Feb 25, 2019 at 5:17 PM Mirko Kämpf <mirko.kae...@gmail.com> wrote: > > Hi, > regarding content versioning, I suggest to search formar like doc-book xml > (it can be anything which allows Separation of content and Style). > With this, we can generate PDF, PPT, Google-Presentations for final > customization. > > The issue is, how to convert a result from a creativity session incl. media > content / sketches / fotos back into such a fundamental format. > > I suggest not to try to build another CMS or publishing Framework, but > rather Focus on the process of content creation/Update. > > Cheers, > Mirko > > Lars Francke <lars.fran...@gmail.com> schrieb am Sa., 23. Feb. 2019, 16:23: > > > On Sat, Feb 23, 2019 at 7:31 PM Sharan Foga <sha...@apache.org> wrote: > > > > > > > > > > > On 2019/02/22 23:12:29, Lars Francke <lars.fran...@gmail.com> wrote: > > > > During the DISCUSS and VOTE threads I tried to postpone any discussion > > > > about the actual content and technical bits but now would be a great > > time > > > > to start. > > > > > > > > I know that Dmitriy was eager to get started and Christofer also > > > explained > > > > his workflow briefly. Maybe you could go into more detail? > > > > Christofer demonstrated his own tooling to us and I really liked it. > > This > > > > could be a great start. > > > > > > > > I'm sorry this is going to be a bit longer and maybe a bit "rambling". > > > Take > > > > it as you will. I just needed to write it down once :) > > > > > > > > When we've done trainings so far they usually consist of a couple of > > > things: > > > > > > > > * Slides (for us usually in Powerpoint) > > > > * Whiteboard sessions (usually the most interesting parts because they > > > > usually are the result of attendee feedback/questions) > > > > * Labs (the actual content, things that attendees need to "solve"/do) > > > > * Lab setup (especially for the larger distributed systems getting a > > > > realistic setup of the tools itself for all attendees isn't trivia > > > > > > > > I'm sure I'm missing something. > > > > > > Thanks Lars - this is good. Off the top of my head a couple of things > > came > > > to mind - the first is testing (to see how much attendees have learned > > and > > > this could be linked to certification which I think was mentioned in one > > of > > > the threads) and the second was a way of collecting feedback about the > > > training - so perhaps a survey > > > > > > > Those are good points I didn't think of. > > > > Tests we have never done by choice but I see that people might be > > interested in them and surveys are something that we probably should have > > done ourselves a long time ago already. So: Definitely. > > > > > > > > What should our scope be? > > > > Our initial idea centered around Slides and Labs. It would be great to > > > also > > > > have something that makes the Labs setup easier but in our experience > > > > that's pretty hard (e.g. corporate firewalls don't allow access to X or > > > Y) > > > > to make generic (that shouldn't stop us from trying!) > > > > > > > > Slides: > > > > I'd love to have a workflow where I can design slides entirelly in > > > > Asciidoc. That makes them easily versionable and composable. Should we > > > > allow multiple formats? If we decide on a text-only format and someone > > > > donates a bunch of courses in Powerpoint. Would we deny that? > > > > > > I think that we would want to accept contribution that is relevant. There > > > may be an overhead to convert the content into a more generic format but > > > that's doable especially if it encourages contributions. > > > > > > > I assume you meant "any contribution"? > > In general I agree but any binary format (e.g. Powerpoint - I'll call it > > binary even though it's really XML now but it's pretty useless for what I'm > > going to mention or PDF) has the problem that doing reviews is tedious to > > impossible. There's no good way (I know of) to create diffs for example and > > people on Linux are left out entirely for Powerpoint. > > > > I currently believe having "one true format" for all of them is a good idea > > (I am happy to be convinced otherwise), maybe with a kind of "staging" area > > of accepted contributons that have yet to be converted and are not coverd > > by "quality guarantees". > > > > > > > > > > > > > > > > > Labs: > > > > Similarly for Labs we've had a good experience with (e.g.) > > > > https://antora.org/ which also allows to create documentation in > > > Asciidoc > > > > and create a website out of it. But there's lots of ideas on how to > > > improve > > > > this (e.g. Notebooks in Zeppelin) and it'll also be way different > > > depending > > > > on the training topic. > > > > > > > > Audience/Customizability/Composability > > > > I would assume that our trainings will also be used by non-commercial > > > folks > > > > or people needing to give a training in-house at their companies. For > > > them > > > > a prepared "deck" with ASF branding is fine but others might want to > > > > incorporate these slides into their own work (see the Legal thread) and > > > > also compose their own out of smaller "components". > > > > So for me a good thing would be if we produce smaller "chapters" of > > > things > > > > that can then be composed however one would like and to make our > > product > > > > customizabile (e.g. custom header, footer, background colors etc.) > > > > > > > > Apache vs. non-Apache // Product vs. non-product > > > > I wouldn't want to limit us to Apache products. I don't see a reason > > not > > > to > > > > also talk about 3rd party tools. Especially if they are tightly > > > integrated > > > > into the ecosystem (e.g. the ELK stack is often used alongside Hadoop). > > > > > > +1 I like the idea and it also could make our content valuable to others > > > outside the ASF > > > > > > > > > > > I also don't see a reason to only focus on single products. A training > > > > could focus on "IoT" and cover lots of products. > > > > > > +1 this will also give the Apache projects visibility of others in the > > > same domain. I'm not really sure how cross pollinated our projects are. > > > > > > > > > > > In a similar vein it doesn't always have to be technical products. I've > > > > already been approached from multiple people about "The Apache Way" > > > > presentations. Now whether they make more sense in ComDev is to be > > > decided. > > > > Maybe Sharan can weigh in? > > > > > > I think Training would be a great place for managing the Apache Way > > > content. In ComDev we've tried to gather and collate this type of content > > > and have ended up with a page of different presentation slides. Each > > person > > > has a different spin on it - so creating something standard as a nice off > > > the shelf template that anyone can use will be great. And I'm happy to > > > ensure we maintain a link and communicate with ComDev regularly so > > > potential contributors know about what we are doing here in Training. > > > > > > > Okay, that's good! > > As you said: There's a dozen of those out there now. > > > > Lars > > > > > > > Thanks > > > Sharan > > > > > > > > > > > Thanks, > > > > Lars > > > > > > > > > -- Sönke Liebau Partner Tel. +49 179 7940878 OpenCore GmbH & Co. KG - Thomas-Mann-Straße 8 - 22880 Wedel - Germany
