Quick Docs in Ask?

Site Help & Feedback
1

(Splitting this topic from https://discussion.fedoraproject.org/t/proposal-migrate-common-bugs-from-the-wiki-to-ask-fedora/71548/ to talk about docs.)

+100 for this.

Also I want to see a similar setup for “QuickDoc” in Ask as well.

2

And if we are already talking about QuickDoc and Documents in general, please include a search field for the QuickDoc. It not matters if we don’t have an own search engine. Just include a Search-field who points to Google or DuckDuckGo.

3

Here’s the issues for docs search. Help wanted!

https://pagure.io/fedora-infrastructure/issue/6750

https://pagure.io/fedora-docs/docs-fp-o/issue/2

1 Like
4

Hmmm. I see the appeal, but I have mixed feelings. Part of the idea of Fedora Docs is to get all of our scattered documentation in one place. The “Quick Docs” thing was meant to be an easy way to get that started from existing scattered wiki pages and other help articles. I definitely expected we’d have search in place sooner. :frowning_face:

Discourse does have a Document Management Plugin, and we could enable that.

Advantages would be:

  • As with the Common Bugs thing, more closely linked with where people are going to get help
  • Less intimidating to dive in: no need to know git workflow, and even if you don’t know markdown you can quickly learn to format posts nicely with the dual-pane edit view Discourse uses.
  • Edit like a wiki
  • There would be search!
  • Each topic has a linked discussion for comments

Disadvantages:

  • Splitting things up from the other docs, again, for people looking it’s nice to have it all in one place
  • We want people to learn the git-based docs workflow for things other than quick docs
  • The git-based docs workflow allows for review and commentary on pull requests, which is nice for more complicated things
  • AsciiDoc more suited for complex technical writing

Also, we’d need some folks dedicated to “gardening” the document repository. We do have folks doing that now for Quick Docs, although not as many as I’d like.

I guess on the balance, I’d rather get that search thing fixed, and maybe figure out how we can more closely integrate. But it’s worth bringing this up with the Docs team. Maybe there’s some other hybrid approach we could take. (Like, maybe even changing the workflow for just that section of Quick Docs to pull from Discourse!)