Documentation migrated to Discourse


#1

The Juju documentation web site has now ceased to use GitHub. Its holding and editing place is now this very Discourse forum.

This means that forum members will be able to edit/create documentation pages themselves, according to the trust level system built into Discourse. Because the web site will be updated automatically, the docs have effectively become a wiki.

The documentation now resides under the Docs category. There is a pinned topic that acts as the table of contents. The sub-category Docs-discuss is to be used for documentation-related subjects (stuff that is not intended to be published on the web site).

Documentation issues are still managed on the GitHub bug tracker.

Writing guidelines

Documentation editors are to use the Documentation guidelines. This will be important for maintaining the quality and the consistency of the documentation.

Version signposting

Previously there were distinct Juju versions you could select on the web site. Going forward, there will be a single documentation link, with its contents being exactly what resides in the ‘Docs’ category on this Discourse site.

There will therefore be the need for editors to “signpost” documented features in order for users to know what version provides what features. See Versioning in the guidelines page for details.

Legacy versions (2.5 and earlier) will be archived for viewing on a separate domain.

Large community-contributed pieces

We may have a place within the table of contents (navigation menu) to link to large community-contributed pieces of text. These pages may also be labelled as such. An example of this are tutorials. There is a concern that such contributions may include a writing style and organisation that differs significantly enough from the existing body of documentation to result in a poor user experience on the web site. It is hoped that such pieces will eventually be kneaded into the rest of the documentation. Ideally, then, editors should strive to base their writing on the style of the existing documentation and make full use of the aforementioned documentation guidelines.

Timeframe

Documentation file import
The documentation has already been imported several times into Discourse and has undergone a QA process. There is still one lingering issue (lack of Markdown support within admonishments) but this is not a blocker. Admonishments also currently suffer from a colour problem.

Web site publishing
The automatic publishing of changes made in Discourse won’t be ready immediately. This will occur by mid-April 2019. Consequently, there will be a window of a few weeks where documentation updates will only be visible within Discourse.


The Juju Show #46 - Machine Learning with Kubeflow March 27th 15:00UTC
#2

Throwing away versioned documentation is a huge no-no and step back from our point of view.


#3

I can understand that but I think that the goal is to have a more single stream of documentation vs completely different pages/urls and such. The examples of things like Python and other documentation that will spell out a command but call out it was added in version X and later or the like. We won’t be tossing away information about what shows up in different versions or the like, but try to make it a single stream vs different streams.

Hopefully that’ll help with your concerns around the version details.


#4

I like this alot! Great work!

Looking forward to the next generation of juju documentation!


#5

Just to mention the main motivation of this is because of things like search engines leading you to out-of-date documentation. By using a stable URL for the best documentation, (and then indicating old compatibility inline), old links/well indexed links still point to the best place to get information. I’ve personally seen searches that pointed at old 1.25 documentation, which we really don’t want.


#6

Exactly my experience too. Finding correct documentation to the current version is/was difficult.

All in all, this is an improved situation.


#7

Just as a side-note since it has come up a lot, searches delivering links to old documentation was because of the websites containing them not implementing canonical links.


#8

I think this will make contributing a lot easier. I think we’ll see a lot more drive-by fixes this way. The github process was quite complex for a simple fix and I’ve had PR’s sit idle for weeks because I was waiting for someone to review my changes.

I also think removing the versioned docs is a good thing, because it eases the maintenance burden a lot. In my opinion the Kubernetes docs are some of the best docs I’ve ever seen and they don’t have versioned docs either. They just specify in the docs which versions introduced a feature.


#9

This new system is a significant obstacle to contribution.

I wanted to fix a typo in the docs.
It’s just a one character fix in a yaml block. I tried to do it myself but the contribution process is very confusing and I couldn’t figure it out.

The “Help improve these docs” link on every doc page points to a page which says that the way to contribute is with Github pull requests. But you don’t accept those anymore, so why does it say that?

I signed up for a Discourse account. (Technically my acceptance was illegal, since the terms say I must get approval from my company to accept the entire agreement on behalf of all 30,000 coworkers in order to submit this one-character patch. Do you really expect people to go through corporate legal departments for such simple stuff? That would take me about 2 months. Yet another barrier to contributing.)

Then once I signed in and got to this page, I tried to edit the page, but there’s no edit button. As a new user I am not ‘trusted’, so there’s no edit button.

If new users can’t contribute from the get-go, that’s a huge issue. In the Github world I can submit my patch and an experienced human will look over it to make sure it’s not crazy. In the discourse world I can’t submit a patch at all.

I don’t see any benefit with the new system. If you want to have stable URLs, just have stable URLs in a site saved on github.


#10

Also, the description in this post itself is ambiguous. After reading it my understanding was that the content changes in Discourse will get automatically pushed to docs.jujucharms.com . But after reading some of these comments now I’m not sure whether that’s the case, or whether docs.jujucharms.com is being abandoned.


#11

Its great that you find these things as they are super valid. To be legaly able to contribute, get clear info on how the contribution process works etc. is massively important to the community. Increasing and simplyfying participation.

I dont know the complete plan from Canonical (that heavily drives this projekt) on this topic atm but this dokumentation move to discourse was at least in my view an improvement mid-term to help beginners get a consistent place to find info. It remains to solve the items you point out if they are accurate.


#12

Sorry for the confusion. I’ve updated the contributing page for the branches visible on the website (2.3, 2.4, 2.5, and devel). It now points to Discourse.


#13

The default trust system is in place and you are at trust level 0.

In order to edit a wiki post you need trust level 1.

You can get to trust level 1 by doing any of the following:

  • Entering at least 5 topics
  • Reading at least 30 posts
  • Spend a total of 10 minutes reading posts

I will add some of this information to the Docs area so people are aware. Thank you for this feedback.


#14

I see the Doc issue you raised and I will respond.


#15

The web site publishing mechanism will kick in in about two weeks time. This is mentioned in my original post. There will also be some domain name changes. For instance, I believe the current branches on docs.jujucharms.com will be archived on old-docs.jujucharms.com and the final web site domain (whose content is in Discourse) may get an entirely new domain name. I’ll keep everyone posted. Thanks for your feedback and concern.


#16

Why will the old docs stay online? This seems like it will only make google search results worse, now you’ll have a version for every Juju version + the new site…

If you really have to keep them up, can you at least add a robots.txt or something to stop google from crawling it?


#17

That’s a good point. We will put an “x-robots-tag: noindex” header in place on old-docs.


#18

This has been done:

$ curl -I https://old-docs.jujucharms.com/2.5/en/
HTTP/2 200 
server: nginx/1.15.6
...
x-robots-tag: noindex
strict-transport-security: max-age=15724800; includeSubDomains