This PR brought up some interesting points we’ve not really discussed before for the Ansible package/core documentation.
The gist of it is - What kind of links to other information should we allow in our docs?
This particular PR is looking to add a link to How To post on this forum. Likely there will be more of those showing up here, so we should decide what our strategy is on the main docs with regard to things like How-To guides showing up here and useful blog posts here and elsewhere.
We could:
1 - Limit all links to official documentation (whether it’s ours or Python, or some other place)
2 - Open up linking to anything useful (stackoverflow, etc etc)
3 - Something in the middle?
If users may delete their own forum posts it might not be such a good idea to permit such links. IMO it’s bad enough as is with “permalinks” sometimes not being "perma"nent. Even Ansible documentation suffers from link rot at times.
OTOH, users will create valuable documentation here sometimes and, as in the PR you link to, it would be a shame to lose track of that.
Is there some way for forum moderators to mark a post as being “valuable doc”? If they could then also make the post immutable, at least until a moderator decides otherwise, it might be a solution.
I don’t have strong feelings on the outcome, but to answer a couple of points from the PR etc:
a - will the url ‘break’ at some point and we don’t notice?
It shouldn’t. The URL comes from the topic name (not the category) so you can move things around at will. Even if the topic is renamed (a rare event after ~5mins of lifetime, generally) Discourse can create redirects. So this should be pretty safe, in my experience.
will the content in the forum post go ‘stale’ and not really be relevant anymore?
Possibly. But so will everything else, including the docs, eventually . That’s not a reason to deny a link here vs a blog post or other external content (though it may be a reason to deny any external links as policy).
In general, they can delete recent posts (not topics) if they have no replies, and even that expires after a short while. Highly privileged users (see Understanding Trust Levels for details) have a lot of rights for editing/fixing things, but IIRC even they can’t delete topics, so this should be pretty safe as it’d be restricted to moderators/admins who should know better.
Absolutely. We’ve obviously got to spend some time deciding exactly what we want from Discourse (it’s very flexible) but as an experiment we’ve created the Guides, FAQs & Howtos section for this kind of thing. Creating topics there is moderated (because not everyone should have the power to decide if something is a Howto), but anyone can reply - and we can move topics over from other places if need be (without affecting the URL, see above).
We could also use a tag for this, but I think it might get lost, we’re planning to use quite a lot of tags
With the factual bit out of the way, I’d vote to allow it. There’s always going to be a grey area for this kind of thing, and since @samccann already identified that there isn’t another place to host it, then this seems a natural option - wiki posts can make sense, but even just a place where people can reply and say “this didn’t work for me” is useful. (BTW I suspect the lack of such a place is why we’ve made such use of HackMD for the last few years).
Regarding URLs - my hope is to make this the home for all our project archives, eventually (because fragmenting them between Google Groups, GitHub Issues, GitHub Discussions, and more is … not good). So you can bet I care about the URLs being stable . I love the fact that I can still go to this URL and get to my original proposal for Discourse for my previous community role - some 6 years ago (and that was imported from Google Groups!). So I would say it’s about as reliable as you’re going to get on the internet
I’d have to look at the Doc code, but I should we not have a CI Tool that checks for dead links on Doc PR’s similar to this github action?
I agree that we should strive to use permanent links, but using CI to alert us of any problems would help. A digging through the current checks on the mentioned PR doesn’t look like it does this. From a search there are several python solutions out there, but no action behind it.
So there is also the possibility of saying ‘this post/blog is so useful it should be in official docs’… and then creating a place for that on docs.ansible.com.
I’m personally inclined to agree with @gwmngilfen comment and take it a bit further - to allow urls to sites other than Ansible community (or official Red Hat) sites. To me the power of open source is to relax some of the product-like rules because there is a lot of useful information out in the real world that our readers can learn from, but may never be something we want in official community documentation.
On the flip side, if I put my traditional techwriter hat on - urls should be only to other doc sites that will remain stable over time (like Python docs). Official Red Hat documentation uses the IBM style guide, which has this to say:
Link to and cite only reliable, authoritative sites. Do not link to sites, such as blogs or wikis, where the information can be edited by unreliable or irresponsible contributors. You can link to blogs and wikis that are owned and maintained by IBM, but consider the cost of maintaining such links and the risk of broken links as such sites change or information is updated. Wikipedia is well moderated and is generally safe to link to. However, before linking to Wikipedia, consider whether the article has problems that are flagged within it; whether it is simply factual or expresses opinions; whether the information is outdated; or even whether the web page has a history of multiple changes.
We could replace IBM with Ansible in the above if we wanted to formalize a strict linking policy…
I think if you replace “Wikipedia” with any given site name, then you have the basis for a policy. So long as we have CI to flag things up for checking, then we can link to things we consider reputable. I would obviously put this forum in that list - it is well-moderated and safe to link to
Even Ansible documentation suffers from link rot at times.
. That’s not a reason to deny a link here vs a blog post or other external content (though it may be a reason to deny any external links as policy).
. I love the fact that I can still go to