I have written a few tutorials I would like to add to the tutorials site. However, I’m hitting a wall trying to follow the guide to run the development site according to the instructions.
Perhaps someone knows what I’m doing wrong or what the issue is.
I feel very dis-encouraged at the moment, having spent two days just trying to get the development environment up for writing a simple tutorial.
=== UPDATE (2018-11-11) ===
I have understood that there is a complimentary repo, https://github.com/ubuntu/tutorial-deployment, I need to dig into. The README in that repo is not clear to me how to use.
=== UPDATE (2018-11-13) ===
Lots of attention from the community on the topic. Haven’t had more time to resolve the technical issues around getting the tutorial-tech-stack to work. Maybe in some time I’ll find more time.
@erik-lonroth I have not traveled down this path of writing the tutorials, but fully agree that we need to lower the bar to make contributing tutorial docs more of a streamline process.
Possibly we can package something simple that will allow users to just write the markdown and run a script that builds the environment, dependencies, and documentation.
At the moment I’m not sure if I’m just not getting it, failing to understand or following the instructions correctly. If thats the case, I apologize already.
However, I think that its worth a thought if the ambitions on creating a technically beautiful tutorial engine, outweigh the need of getting a community to be able to contribute.
I have very little insight in how the community contributes to the documentation today. But am I the only one having this issue?
@pmatulis thanx for your efforts. I have a sincere wish to help out, but my general concern is ‘how high is the entry level to contribute to the juju community today?’
Documentation, examples, tutorials and community support is critical to its success.
I’m amazed, but also concerned, that such a great software tool (juju/charms) hasn’t got those things in super-good shape.
I’m comparing to Android learning guides/tutorial which has a really good series of examples/lessons/tutorials getting you from zero, to, expert. I think that kind of documentation/education is what I would love to discuss and contribute to around juju.
Again, I hope you take my critisism as a sincere wish to make the juju experience great.
@erik-lonroth The Juju documentation is hosted on http://docs.jujucharms.com and the tutorials (of any subject really) is hosted on http://tutorials.ubuntu.com. You can open a documentation issue here to let us know about any missing parts. The documentation is currently managed within GitHub via pull requests and reviews, but soon (January?) contributions (to devel only) will be entered into the system right here on Discourse (and published pretty much instantaneously on the web site). The idea is that this will allow for more contributions.
Just to hop in, damn sorry you’ve hit these issues Erik. We love the other tutorial you did and really appreciate the hard work that goes into this stuff. We know it’s a pain to get going but it’s awesome when it helps other folks out. For the tutorials side of stuff we’re reaching out to the folks that manage that and we’ll see what we can get pulled together. Unfortunately it’s not something in our control as we’ve centralized the tutorial stuff (which is really nice once it’s up).
For Juju content we’re really hoping this move to the discourse site is the lowest barrier to entry we can get folks. Just plunk content in here. I know we’re happy to help edit, categorize, ask questions, etc. It really lets more folks get involved and now that you mention it I know that it’d be great to get edit rights to some of the community so we can grow the team helping to keep things updated and as awesome as possible. If you’re interested let me know and I’d love to get some more folks setup for it.
Finally, the docs site is scheduled to get over here. Again, it’s something that teams in Canonical are doing/prototyping. I know the snap folks have led the way on having documentation in Discourse where they can be collaborated on more easily. There’s a team working on a migration tool to get all of our github docs migrated into a Category in here as well and they’re going to use the same tool for maas, lxd, and Juju. We’re down the list of folks to get the tool to migrate so we’re holding steady at the moment while we wait for that progress to come our way.
In the meantime though I want to encourage everyone to use this discourse site as a dumping ground for notes, tutorials, questions, idea sharing, etc. It really is our home to make of it what we will and hope no one feels discouraged inside these virtual walls here.
Let me know if I can do anything to help out @erik-lonroth. What’s the tutorial updates you’re looking to make? I’m curious what’s in the pipeline.
Thanx for taking the issue on documentation and tutorials/education seriously. It shows the intent is there and I’m happy to contribute. I definitely feel less discouraged from that kind of attention. But time is limited and these things are needed…
My thoughts:
Adding tutorials/docs shouldn’t be over-engineered. After all, my guess is that there isn’t avalanches of contributions today to juju docs? Why just no settle with “.md” files in a dedicated repo with someone just maintaining a README.md file with some categories and recommended entry-points?
Lowering entry level increases contributions. People loving documentation aren’t necessarily programmers or DevOps. The decision to have a full blown git,md,docker, yarn,nmp environment pulled up just to be able to write a tutorial/docs makes no sense at all? What happened to a simple wiki?
I’m sure Canonical has ambitions to centralize documentation/tutorials. But I don’t work for Canonical. I care for the open source JUJU project which I can’t see benefit from whatever Canonical’s ambitions are. These things doesn’t need to be in conflict, but its a delicate line to walk between “governing an open source community” vs “pushing a proprietary product development with an open source license”. I’m not saying I can walk it =)
These issues leads to thoughts on “what is the grand plan for growing and nurturing the project and its community?” I’m my opinion, JUJU should/could have ambitions to be the #1 orchestration tool in the world. If that is to happen, the community needs to grow and be nurtured. Perhaps it is? Maybe I’m just way off? In that case, I’m again apologizing and would love to dive into more information.
Lastly, and back on topic. From this discussion, I’m again left confused with multiple options on where to place my tutorials. Discourse? Tutorials? Blogg? In my situation at the moment, I need to create these next tutorials in the format for “tutorials.ubuntu.com” (which lead me to this predicament sigh). After all, Part 1 is already in there and Part 2 + Part 3 are meant to be following up on those. I would like to write a Part 4 which digs into Interfaces, but its a lot of work writing it so I’m taking a bit of a step back at the moment to get a grip on this whole situation.
Again, I love the work you all do. My criticism is brutally honest but with the intent to help and make it better.
Sorry for the confusion. Our goal is to get all Juju related material here in discourse and to build a community around Juju here on discourse and to make sure that the barrier to entry, the feeling of camaraderie, etc is at its best here.
The tutorials site is something that’s a bit more professional. Something more used as marketing material and linked to folks that need/want the polish and structure. In my mind, a good tutorial would start here with discussion, reviews, improvements, etc. Only when we had something great here would then we might engage with the tooling/etc to get it polished up and onto the tutorials site. Yes, the overhead is more there. However, it’s the extra goal and as you note, there’s not really a community around the tutorials site. The community is here.
OK, so how do you envision I start such a thing here on Discourse? I’m prepared to publish here my tutorials part 1,2,3 immediately if you can show me how and/or where. (@pmatulis might need to consider the fate for Part 1 currently on tutorials.ubuntu.com as it will hang-in-the-air without part 2,3 along with it.) I won’t push any more for the tutorials site then…
I’d suggest just starting with a post here on the Users category. Maybe prefix the title with “Tutorial: xxxx” and leverage the ability to do things like code blocks, images/screenshots, etc and list it out from start to finish.
The great thing about the group editing is that as folks repeat it and find tweaks or notes, or need to update it to work with later releases of Ubuntu/Juju/etc the community has the ability to make those tweaks in a fairly trivial fashion.
