On Feb 3, 2016 11:39 AM, "David Ashley" w.david.ashley@gmail.com wrote:

Pete -

I looked around on the Fedora Wiki but I could not find any documentation

on how Fedora Docs are published. Could you provide me with a pointer? I have some time and I thought I would try to get myself up-to-speed .

David Ashley

Hey David,

The current process is more or less covered in the documentation guide under drafts at docs.fp.o . There is a missing step; the web.git repo is built with publican2 so the action needs to happen in ... an F18 vm, iirc. Publican handles most of the work; the html content is rsynced hourly by public facing proxies. Other that some redirects that live in ansible, web.git is the whole site.

FWIW, I'm feeling motivated to work on the replacement this week, we should get together and whiteboard it if you're still interested in getting involved.

--Pete

On Feb 3, 2016 11:54 AM, "David Ashley" w.david.ashley@gmail.com wrote:

I would absolutely like to get involved. I am free every night this week

and also on Friday afternoon. I also have some time on Saturday afternoon and some on Sunday if that is better for you.

David Ashley

Awesome! I think a literal whiteboard would really help, I'll see if I can get a room at the office with a whiteboard-painted wall and get back to you with some options.

--Pete

Works for me. I will meet you at 6PM at the Rackspace front door.

David Ashley

On 02/03/2016 01:20 PM, Pete Travis wrote:

On Feb 3, 2016 12:02 PM, "Pete Travis" <me@petetravis.com mailto:me@petetravis.com> wrote:

...

On Feb 3, 2016 11:54 AM, "David Ashley" <w.david.ashley@gmail.com

mailto:w.david.ashley@gmail.com> wrote:

...

...

I would absolutely like to get involved. I am free every night

this week and also on Friday afternoon. I also have some time on Saturday afternoon and some on Sunday if that is better for you.

...

...

David Ashley

Awesome! I think a literal whiteboard would really help, I'll see

if I can get a room at the office with a whiteboard-painted wall and get back to you with some options.

...

--Pete

I can get one of the smaller rooms up front, near where the WriteTheDocs meet up is held, this evening from 6-8. Does that work for you? If not, other evenings are feasible too.

--Pete

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Wed, Feb 03, 2016 at 01:31:00PM -0600, Pete Travis wrote:

Great, see you soon!

What are the chances of visiting the Docs strategy?

Over time, we've seen that not just the process of writing, editing, and publishing docs is difficult for new contributors. (I know because I was one.) But the *strategy* -- which is focused on long form books for a fast-moving distribution -- is somewhat of a mismatch.

Short articles and wiki pages and other similar focused docs, on the other hand, have really eaten our lunch, as far as being the places users go to find information. I routinely run into users who tell me they find answers for how to do things for Fedora on StackExchange, Arch wiki, Ubuntu forums, and so forth.

Meanwhile, we have all sorts of easier tools for writing, editing, revision control, and publishing out there. For instance, AsciiDoc has really been embraced across a lot of technical docs communities. Nowadays, just about anyone can edit an ASCII based document in a web based editor on a git forge (like Github or Pagure), and submit a pull request without having to jump through any preliminary hoops.

For a high level view of how this is working for other very vibrant open source communities, q.v.: https://opensource.com/business/15/7/continuous-integration-and-continuous-d...

Here's another cue: It would be great for the future of Fedora if we could build additional value not just for our users but also our sponsor Red Hat. We do that quite handily with the distribution, as we integrate new tech into Fedora releases. But what if we could do this with the strategy in Docs team? My hope is there are folks in Red Hat content services who would be interested in pitching in to help.

But whether that happens or not, refocusing on smaller chunks of knowledge, and making it easier and more frictionless for people to create and change those chunks, is one of the best things the Docs team could do to meet the next wave of change coming in Fedora. (I'm looking at you, Atomic, xdg-app, Cloud-fu, etc.)

On Thu, 2016-02-04 at 11:54 +0100, Paul W. Frields wrote:

Short articles and wiki pages and other similar focused docs, on the other hand, have really eaten our lunch, as far as being the places users go to find information.  I routinely run into users who tell me they find answers for how to do things for Fedora on StackExchange, Arch wiki, Ubuntu forums, and so forth.

The challenge with short articles is maintenance.  Google anything on Fedora or Linux for that matter, and almost everything will be sadly out of date or just plain incorrect.  That even applies to our own wiki, in spite of numerous attempts at wiki gardening.

With a small number of documentation products, it is a lot easier to keep track of the documents and identify them as to the version they reflect.

It makes me wonder whether some of the web-based git tools might help (OK, I'm a major git fanboy).  Most of the public git repositories include a wiki.  If we could somehow tie that wiki to branches or even tags, perhaps we could develop a more edible set of documents that would allow the user to find not only the information needed, but also for the appropriate period in history.

Just noodling.

(BTW, it looks like it may be a while before I can join the meetings again.  This Flint water thing has me on the phone with the state emergency operations center every day at meeting time.)

--McD

I am little beyond a long-term lurker around here, but at the risk of being immediately (and possibly rightly) despised, I will say that a big part of the reason for that is my reluctance to even attempt to figure out how to submit documentation changes or additions. Despite lurking for a while, I still know embarrassingly little about how our documentation is created or even what the high-level architecture is for our documentation; for some reason we have some sort of build process beyond simply modifying content in a text-based editor and clicking a button and I don't know why. Maybe figuring that out would only take an hour of my time, or maybe it requires some sort of relationship with other Docs members so that I can be mentored or who-knows-what, but the fact that this is harder than something anyone can immediately figure out in two seconds on the Internet is enough to dissuade me from bothering. It's much easier to write guides as I determine the information is needed and post them to my blog; the administrative overhead I incur during those operations is nearly non-existent. I simply write text, click a button, and am done.

Now, I may be so n00blar that I have an inadequate understanding of the reasons behind the Fedora Docs infrastructure design choices, but when I first envisioned participating in the Docs group, I expected a mega-simple process in which I simply use a browser to navigate to the content in need of updating or correcting, make the addition or correction, and press a button to trigger the pull request. I was further hoping it'd all be heavily integrated with man pages, but that appears not to be the case. In my documentation dream world, I am simply permitted to submit pull requests for man page modifications for any Fedora package from one streamlined interface, but that appears not to be something we do.

Why our solution is not that simple, I do not know. Is it really merely that we're afraid of poorly maintained Wiki articles? If so, some sort of aging indicator that pushes stale content to the top of a "To Do" list or something seems like a good way to keep maintenance focused. Rather than trying to decide on a short-form or long-form format into which we will cram documentation, can we not simply permit everything to be a bit more amorphous, lengthening and shortening as the needs of the community demand? I was expecting something like Arch Linux's renowned ArchWiki documentation system, for example. If such a system could be integrated intelligently with relevant man pages (even just links to relevant GitHub content would be a nice way to funnel interested parties to other packages' documentation so that it can be maintained as well), such a solution would be near-perfect, in my eyes.

Wouldn't it be nice if it were that simple? It'd be nice if everyone on the Internet could easily and quickly submit documentation which simply awaits the judgment and subsequent rejection or integration by community-elected moderators (e.g. members of this group, or what-have-you).

Maybe I'm overlooking obvious complexities, but I don't know what they are. Why don't we simply pursue a flexible, easy-to-use ArchWiki-esque solution and focus on streamlining maintenance to address concerns in that field? As has been observed above, such Wiki-based systems are those which are preferred by end users, and for obvious and good reason, if you ask me. I say we give the people what they want and thereby open the field of contributors to anyone who should pass by the Wiki site, which should also make the lives of maintainers easier in the process, right?

My apologies for any time wasted on account of my ignorance.

-Dylan

On Thu, Feb 4, 2016 at 8:28 AM, Matthew Miller mattdm@fedoraproject.org wrote:

On Thu, Feb 04, 2016 at 08:20:27AM -0500, John J. McDonough wrote:

...

The challenge with short articles is maintenance. Google anything on Fedora or Linux for that matter, and almost everything will be sadly out of date or just plain incorrect. That even applies to our own wiki, in spite of numerous attempts at wiki gardening.

I've said this before, but I will buy a case of $PREFERRED_BEVERAGE for whoever implements pirate-mode aging a la Trello (http://help.trello.com/article/820-card-aging) for any new docs solution.

And another for anyone who does it for the wiki.

-- Matthew Miller mattdm@fedoraproject.org Fedora Project Leader -- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Thu, Feb 04, 2016 at 02:50:39PM +0000, Ian Malone wrote:

On the particular issue of man pages, they belong to upstream projects, which is where those documentation efforts should usually go. I don't know if anyone (in any distro) has ever packaged patches for man pages. Fedora Docs is really about the additional

FWIW, Debian _does_ often generate man pages for packages which do not have them upstream.

On 02/04/2016 12:52 PM, Matthew Miller wrote:

On Thu, Feb 04, 2016 at 02:50:39PM +0000, Ian Malone wrote:

...

On the particular issue of man pages, they belong to upstream projects, which is where those documentation efforts should usually go. I don't know if anyone (in any distro) has ever packaged patches for man pages. Fedora Docs is really about the additional

FWIW, Debian _does_ often generate man pages for packages which do not have them upstream.

the main problem is that Debian keep man pages with them instead of sending to upstream.

El 04/02/2016 08:52, "Matthew Miller" mattdm@fedoraproject.org escribió:

On Thu, Feb 04, 2016 at 02:50:39PM +0000, Ian Malone wrote:

...

On the particular issue of man pages, they belong to upstream projects, which is where those documentation efforts should usually go. I don't know if anyone (in any distro) has ever packaged patches for man pages. Fedora Docs is really about the additional

FWIW, Debian _does_ often generate man pages for packages which do not have them upstream.

rpmlint show a warning for executables in /usr/bin with out a manpage but packaging guidelines do not requiere all executables in /bin to have a manpage, maybe a update to packaging guidelines can help

Send from my phone

On Thu, Feb 04, 2016 at 08:20:27AM -0500, John J. McDonough wrote:

On Thu, 2016-02-04 at 11:54 +0100, Paul W. Frields wrote:

...

Short articles and wiki pages and other similar focused docs, on the other hand, have really eaten our lunch, as far as being the places users go to find information.  I routinely run into users who tell me they find answers for how to do things for Fedora on StackExchange, Arch wiki, Ubuntu forums, and so forth.

The challenge with short articles is maintenance.  Google anything on Fedora or Linux for that matter, and almost everything will be sadly out of date or just plain incorrect.  That even applies to our own wiki, in spite of numerous attempts at wiki gardening.

(1) The Docs team efforts haven't really gone to short articles, but rather to long works that are even harder to deal with, not to mention off-putting to new contributors (whose long tail is supposed to be the focus of growing a community, or subcommunity like Docs).

(2) The wiki is not somewhere we want to send users, so it's not relevant to my topic -- even though you are exactly right about it. :-)

With a small number of documentation products, it is a lot easier to keep track of the documents and identify them as to the version they reflect.

This is true when you constrain yourself to the toolset now in use. But I contend it can be done more easily with more, smaller docs with different tools.

It makes me wonder whether some of the web-based git tools might help (OK, I'm a major git fanboy).  Most of the public git repositories include a wiki.  If we could somehow tie that wiki to branches or even tags, perhaps we could develop a more edible set of documents that would allow the user to find not only the information needed, but also for the appropriate period in history.

You're on the right track with git management here. Git solutions on the web already allow inline editing by anyone. They can submit a pull request without being anyone "special" in a given project.

Drive-by contributions are perfect for docs (and really they're the lifeblood all open source projects would love to have). I contend we should optimize for that, because all other contributors' lives get easier as a result -- riding the wave.

I am also contending that the Docs team should not be developing a solution on its own. There are too many tools out there already waiting to be used for this purpose. Instead, identify some best of breed tools that fit together for this purpose.

On Feb 4, 2016 12:15, "Pete Travis" me@petetravis.com wrote:

On Feb 4, 2016 10:26, "Paul W. Frields" stickster@gmail.com wrote:

...

On Thu, Feb 04, 2016 at 08:20:27AM -0500, John J. McDonough wrote:

...

On Thu, 2016-02-04 at 11:54 +0100, Paul W. Frields wrote:

...

Short articles and wiki pages and other similar focused docs, on the other hand, have really eaten our lunch, as far as being the places users go to find information. I routinely run into users who tell

me

...

...

...

they find answers for how to do things for Fedora on StackExchange, Arch wiki, Ubuntu forums, and so forth.

The challenge with short articles is maintenance. Google anything on Fedora or Linux for that matter, and almost everything will be sadly out of date or just plain incorrect. That even applies to our own wiki, in spite of numerous attempts at wiki gardening.

(1) The Docs team efforts haven't really gone to short articles, but rather to long works that are even harder to deal with, not to mention off-putting to new contributors (whose long tail is supposed to be the focus of growing a community, or subcommunity like Docs).

(2) The wiki is not somewhere we want to send users, so it's not relevant to my topic -- even though you are exactly right about it. :-)

...

With a small number of documentation products, it is a lot easier to keep track of the documents and identify them as to the version they reflect.

This is true when you constrain yourself to the toolset now in use. But I contend it can be done more easily with more, smaller docs with different tools.

...

It makes me wonder whether some of the web-based git tools might help (OK, I'm a major git fanboy). Most of the public git repositories include a wiki. If we could somehow tie that wiki to branches or even tags, perhaps we could develop a more edible set of documents that would allow the user to find not only the information needed, but also for the appropriate period in history.

You're on the right track with git management here. Git solutions on the web already allow inline editing by anyone. They can submit a pull request without being anyone "special" in a given project.

Drive-by contributions are perfect for docs (and really they're the lifeblood all open source projects would love to have). I contend we should optimize for that, because all other contributors' lives get easier as a result -- riding the wave.

I am also contending that the Docs team should not be developing a solution on its own. There are too many tools out there already waiting to be used for this purpose. Instead, identify some best of breed tools that fit together for this purpose.

-- Paul W. Frields

You've quite effectively recapped the conversations we've been having for

a year or two now :)

The core issue *is* the tooling; with some well defined constraints:

• Infra wants static content
• writers want their preferred markup
• the current platform doesn't meet those needs or address the other

issues you mentioned

• We really like using a git based workflow

I didn't find a thing that met those needs, so I've been trying to write

one that can use existing html renderers, throw a menu on top, and handle the publishing process in an event-driven CICD type way so those drive-by contributions are easy, and writers can focus on writing. Is roll-your-own the best approach? Maybe not; it might be better to buy into one specific markup and find a platform that meets the other needs.

Frankly, this needs an FTE for a while, regardless of the direction we

take, or the conversation will keep repeating until volunteers scrounge enough time to fix it.

--Pete

Oh, and I am vaguely familiar with the specific CICD docs platform addressed in the opensource.com article you referenced; some of the technical writers that work with it are just down the hall, literally, and one of the meetups David and I attended gave a decent overview of it. It's an entire scale-out cloud application stack with a handful of dedicated sysadmins to mind it, built on http://deconst.horse and some more. There would be a lot of packaging, debundling, and deployment work to use it. I heard rumblings recently that the solution is changing; not enough to really speak on the changes, but enough that my internal team's public writing ventures are on hold until it settles down.

--Pete

In the interest of not letting this rehash of a year-long conversation die (like the last one, apparently?), could you explain more about the following items, Pete? I've put your text in bold and my questions in plaintext. If I'm going about this all wrong, let me know, but from where I stand, I can't help but think this isn't as difficult as it's being made out to be.

*- Infra wants static content*

I don't know what "Infra" is (the...Infra...structure...team?) or what is meant by "static content." Do you mean some group of stakeholders wants manuals which can be published in a permanent format so that it does not change until the new version or whatever? If so, meeting that demand alongside more dynamic, progressive content seems fairly easy as long as whatever solution we go with has the ability to simply snapshot documentation and compile it for presentation and archival, but this seems like it ought to be a very secondary concern beneath up-to-date, accurate, well-maintained documentation. End users just need to be directed to the correct documentation, and with a well-moderated dynamic content model, the most recent stuff should be the correct stuff. We could have snapshots of the content as it was at the time of release for previous Fedora versions or something for posterity, but aside from that, it seems the primary concern is keeping documentation fresh and accurate.

*- writers want their preferred markup*

What writers are actually demanding particular markup support? Do we have a list of demands? I have no idea what kind of person would be like "Well if it's not XML, I'm not writing it!" but maybe they exist. Is this really a significant obstacle? I'd settle for documentation written in good old fashioned UNIX-style plaintext, myself. The markup support seems like a tertiary concern to me. I'd value easily modified, up-to-date plaintext documentation way above difficult-to-modify, outdated documentation that has to go through an elaborate build process so that it can be delivered in a variety of pretty formats.

*- the current platform doesn't meet those needs or address the other issues you mentioned*

I think Paul is focused on the right points: our primary concern should be providing a documentation platform which makes it incredibly easy to locate the right information and submit drive-by contributions. We can all benefit from such a solution, and that's the way to make sure documentation gets maintained.

*- We really like using a git based workflow*

Maybe some elaboration could help? I mean, I like Git, too, but it might be overkill for this matter?

As I said before, I don't see why we don't just use an ArchWiki-style solution. Of the above points, I guess 1 and 2 might be against it, but I don't really understand them yet. Other than that, it seems a simple Wiki is enough to solve our major problems here, no? GitBook seems cool, too.

It seems like we're stuck in a morass where we're crippling ourselves by trying to fully satisfy a large spectrum of concerns as though they're all equal. My guess is that we can trim away the less critical stuff (like support for a variety of markup languages or the delivery of static content in a variety of formats) and dramatically simplify the solution with a focus on getting content flowing more freely and consistently.

-Dylan

On Thu, Feb 4, 2016 at 3:03 PM, Bryan Sutherland <bryan.sutherland@gmail.com

wrote:

​Have you taken a look at the GitBook ( https://github.com/GitbookIO/gitbook and https://www.gitbook.com/). It's a node application that builds books/documentation from Markdown/ASCIIDoc files.

Just a thought...

Bryan​

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On 2/4/2016 9:50 PM, Pete Travis wrote:

On 02/04/2016 03:00 PM, Dylan Combs wrote:

...

In the interest of not letting this rehash of a year-long conversation die (like the last one, apparently?), could you explain more about the following items, Pete? I've put your text in bold and my questions in plaintext. If I'm going about this all wrong, let me know, but from where I stand, I can't help but think this isn't as difficult as it's being made out to be.

*- Infra wants static content*

I don't know what "Infra" is (the...Infra...structure...team?) or what is meant by "static content." Do you mean some group of stakeholders wants manuals which can be published in a permanent format so that it does not change until the new version or whatever? If so, meeting that demand alongside more dynamic, progressive content seems fairly easy as long as whatever solution we go with has the ability to simply snapshot documentation and compile it for presentation and archival, but this seems like it ought to be a very secondary concern beneath up-to-date, accurate, well-maintained documentation. End users just need to be directed to the correct documentation, and with a well-moderated dynamic content model, the most recent stuff should be the correct stuff. We could have snapshots of the content as it was at the time of release for previous Fedora versions or something for posterity, but aside from that, it seems the primary concern is keeping documentation fresh and accurate.

Infra, as in the Fedora Infrastructure team that would provide the resources required to run shared tools and public websites. Dynamically generated content typically uses server-side code and a database backend to generate webpage content, whereas static content is prerendered html files that do not require server side processing. The maintenance burden on infrastructure and sysadmins for distributing flat files is dramatically lower than the investment required for a web application, especially at scale. Regenerating a webpage when the content changes requires far less resources than regenerating the webpage every time it is requested by a visitor to the site.

Your observations are equally valid for both dynamic and static content distribution models.

...

*- writers want their preferred markup*

What writers are actually demanding particular markup support? Do we have a list of demands? I have no idea what kind of person would be like "Well if it's not XML, I'm not writing it!" but maybe they exist. Is this really a significant obstacle? I'd settle for documentation written in good old fashioned UNIX-style plaintext, myself. The markup support seems like a tertiary concern to me. I'd value easily modified, up-to-date plaintext documentation way above difficult-to-modify, outdated documentation that has to go through an elaborate build process so that it can be delivered in a variety of pretty formats.

I haven't come across any outright demands, but whenever the conversation comes up, people do voice preferences.

We have an active group of content engineering folks that are able to leverage Fedora Docs as the 'upstream' for their work on Red Hat docs, and I am concerned about making contribution less appealing for them by requiring a departure from the markup they use 'downstream'.

There are developers and content creators in the community already conversant in markdown, restructuredtext, asciidoc, whatever. Supporting formats that people already know and use makes participation easier for them, and offers the opportunity to reuse existing content. A plaintext site would lead to a diaspora of bespoke formatting conventions, and the ultimate result would either be awkwardly inconsistent, or the emergence of a new markup standard. Neither appeal to me.

I've heard "I don't want to write in DocBook, but I would write in $this" for at least seven values of $this. Often enough that choosing a different only and mandatory markup language is not appealing.

...

*- the current platform doesn't meet those needs or address the other issues you mentioned*

I think Paul is focused on the right points: our primary concern should be providing a documentation platform which makes it incredibly easy to locate the right information and submit drive-by contributions. We can all benefit from such a solution, and that's the way to make sure documentation gets maintained.

I don't disagree with Paul's observations, and have said most all of it myself. It should be easy to contribute to Docs, it should not be a burden to contribute an article or an edit to an article, casual participants should not have to worry about the publishing infrastructure. Making that happen for a distributed group of participants with varied levels of engagement working on a large, diverse body of content that will be globally distributed at scale is less simple; you must offload the complexity into the platform in order for users of the platform to experience that ease.

...

*- We really like using a git based workflow*

Maybe some elaboration could help? I mean, I like Git, too, but it might be overkill for this matter?

As I said before, I don't see why we don't just use an ArchWiki-style solution. Of the above points, I guess 1 and 2 might be against it, but I don't really understand them yet. Other than that, it seems a simple Wiki is enough to solve our major problems here, no? GitBook seems cool, too.

I have personal complaints about wikis, but setting those aside, the Fedora Project does not have a strong wiki gardening culture. The state of the current wiki would be the fate of another wiki, because the people we want to participate already deal with wikis that way. The static vs dynamic content argument applies, and to a lesser extent, so does the markup argument.

...

It seems like we're stuck in a morass where we're crippling ourselves by trying to fully satisfy a large spectrum of concerns as though they're all equal. My guess is that we can trim away the less critical stuff (like support for a variety of markup languages or the delivery of static content in a variety of formats) and dramatically simplify the solution with a focus on getting content flowing more freely and consistently.

-Dylan

I'm willing to give up on a variety of output formats, but that doesn't seem to be an especially challenging part of the puzzle. Presenting the content in an organized and structured way, without adding a ton of work to maintain the organization and structure of the content, is. We don't need to support a variety of markup formats out of the box, but the *potential* to support more than one format is IMO a requirement.

The morass is real, and so are the problems that need to be solved to get out of it. You're welcome to help find a solution, we'd all be exited to find something that meets whatever needs the group can agree on. If you're interested in some historical context, https://lists.fedoraproject.org/pipermail/docs/2015-February/016015.html and replies would be a good place to start.

"I agree with Pete on this, but I also see Dillin's point. When I was doing my revisions on the accessibility guide, The guide was not in a format that could be easily edited. I believe the format was docbook, which is some sort of xml. I would much prefer some form of markdown, which I know a little of. The specific variety of markdown isn't important, but I cannot write xml cintax without breaking it. Most of you probably use gui programs which autogenerate this xml, but I don't believe any of those are accessible, so I have to use a formatter such as gedit, and while it can read the files just fine, it doesn't run any validation tests on the cintax when I'm writing it. I had to generate a plain text copy, and send it too ... was it hear or pete? I can't remember, for review and modification. This brings up one other point. Is there a reason *all* of the docs aren't regenerated when a new fedora release is made? Accepting of course that not all of them are relevant or actively maintained? The reason I made the changes to the fedora a11y guide is so that potential users could immediately find a good, up to date guide on linux accessibility in general, and fedora in particular but I couldn't find the guide easily. Should this be brought up to someone in fedora to have the a11y guide put somewhere prominently, so disabled users can easily find it? I'll even go so far as to suggest that it be included on live images, but since we don't ship fedora docs on images at all, this seems a little unreasonable. Thoughts? Kendell clark"

...

On Thu, Feb 4, 2016 at 3:03 PM, Bryan Sutherland <bryan.sutherland@gmail.com

...

wrote: ​Have you taken a look at the GitBook ( https://github.com/GitbookIO/gitbook and https://www.gitbook.com/). It's a node application that builds books/documentation from Markdown/ASCIIDoc files.

Just a thought...

Bryan​

I hadn't, will read up on that next. I've been looking at hugo, https://gohugo.io , this evening; it could be an interesting fit. I do think it would be valuable in the long run to avoid getting tied to a particular format (or at least consider that when evaluating options) and hugo has a modular architecture to plug in external helpers for various input formats.

-- Pete

docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Feb 5, 2016 06:31, "Paul W. Frields" stickster@gmail.com wrote:

On Thu, Feb 04, 2016 at 09:50:59PM -0600, Pete Travis wrote:

...

On 02/04/2016 03:00 PM, Dylan Combs wrote:

...

*- writers want their preferred markup*

What writers are actually demanding particular markup support? Do we

have

...

...

a list of demands? I have no idea what kind of person would be like

"Well

...

...

if it's not XML, I'm not writing it!" but maybe they exist. Is this

really

...

...

a significant obstacle? I'd settle for documentation written in good

old

...

...

fashioned UNIX-style plaintext, myself. The markup support seems

like a

...

...

tertiary concern to me. I'd value easily modified, up-to-date

plaintext

...

...

documentation way above difficult-to-modify, outdated documentation

that

...

...

has to go through an elaborate build process so that it can be

delivered in

...

...

a variety of pretty formats.

I haven't come across any outright demands, but whenever the conversation comes up, people do voice preferences.

We have an active group of content engineering folks that are able to leverage Fedora Docs as the 'upstream' for their work on Red Hat docs, and I am concerned about making contribution less appealing for them by requiring a departure from the markup they use 'downstream'.

How would it affect this discussion if we were able to get some of the Red Hat content folks on board with both of: (1) the model of smaller, more modular docs; (2) tooling that worked like a git/pull-request model?

I ask because I'm located near some of these guys this weekend and part of next week. It's a good opportunity to see if we can build some project work around this idea, and break the cycle of "we're stuck because this is really hard and takes time" -- which is ABSOLUTELY VALID, and a problem I'm familiar with from previous lives. ;-)

... snip ...

In short: The tools should do the work, not the people. Spot on.

And as Pete said, nothing I brought up was really novel. I was moved to reiterate after leafing through some of the current docs.fp.o.

As I mentioned above, I'm really interested in getting some content services folks involved in the conversation. But I feel that should happen because Pete and other Docs folks *want* it to happen, not because I happen to be near them this week.

So I guess my question a few paragraphs back still holds: if we can get some resources for this (IOW, people/time/passion), would joint work be of interest?

-- Paul W. Frields

You are absolutely empowered to approach content services folks in Brno or Raleigh or your neighbor's geeky kid about getting involved with this conversation. I'm wary of replicating content services' current tooling without gaining committed maintainers, but we can cross that bridge when we come to it.

--Pete

On Thu, Feb 04, 2016 at 09:50:59PM -0600, Pete Travis wrote:

I have personal complaints about wikis, but setting those aside, the Fedora Project does not have a strong wiki gardening culture. The state of the current wiki would be the fate of another wiki, because the people we want to participate already deal with wikis that way. The

Agreed.

Once we have a new docs site in place, I'd like to place a big banner at the top of the wiki for non-logged-in users:

The Fedora Project wiki is a dynamic workspace for Fedora contributors. Think of it as a sort of digital office whiteboard.

If you're looking for documentation for the Fedora operating system, please visit http://docs.fedoraproject.org/

On 09/02/16 10:10, Ryan Lerch wrote:

On 05/02/16 06:03, Bryan Sutherland wrote:

...

​ Have you taken a look at the GitBook (https://github.com/GitbookIO/gitbook and https://www.gitbook.com/). It's a node application that builds books/documentation from Markdown/ASCIIDoc files.

Just a thought...

Bryan ​

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

We really need to nail down what we want the content to be, how it is structured, and layed out before discussing any toolchain changes.

IMHO, Having many small articles that address a single point or question are much more maintainable and approachable (both for readers and writers). For example, if you want to know how to open a specific port on Fedora, what would you do? -- type "How do i open a port in Fedora?" into your favourite search engine. At the moment, the top hit here is our wikipage on IPtables, and the Fedora Networking guide is not in the first page. (even if you know there is a networking guide, finding that simple nugget of information involves digging through the whole book).

Well if you are going to ignore tool chains and work flows, which IMO is a very good idea, then I'd suggest also taking a look at which docs sites are the most successful and consider doing a similar thing.

i.e. it's pretty obvious from a simple google search that gardened wikis and forums are much more popular than any other form of docs publication for Open Source communities. I don't just mean google hits, I mean participation. It's not even close.

The only people using monolithic, heavy weight, processes are the enterprise vendors, and I include Red Hat in that, who don't want drive by participation.

If the goal is to get more participants, then if it's not a wiki or a Q&A forum, then you are knowingly choosing a tool that is less successful in achieving this goal.

But we have flogged this horse repeatedly and I can't see the basic approach being changed regardless of it's very predictable impact on Fedora docs participation.

Cheers, Jeff.

On 09/02/16 18:51, Matthew Miller wrote:

On Tue, Feb 09, 2016 at 12:37:58PM +1000, Jeff Fearn wrote:

...

If the goal is to get more participants, then if it's not a wiki or a Q&A forum, then you are knowingly choosing a tool that is less successful in achieving this goal.

I don't think this premise is true at all. We're talking about something like http://readthedocs.org/,

The premise is that barriers to entry are greater in tools that don't offer easy to participate interfaces like wikis, forums, and Q&A sites (which IMO are just forums with some fancy CSS).

If you published to RTD right now, which is trivial, would it affect participation in any way?

which is *way* more successful than most wikis.

You are comparing places where communities create content to a place communities publish content.

RTD is a place for communities to publish content they have already have; it doesn't address how those communities get the content to publish or edit & maintain it.

In fact, I think gardened wikis that work are the exceptions rather than the rule (Arch docs, Wikipedia, and nothing else at any scale).

Successful docs sites are also the exception rather than the rule.

I don't know how you missed mentioning Ubuntu, they are clearly the gold standard in community participation for documentation.

And forums? Gah! They're a nightmare and part of the problem. Stack Exchange is successful because it very strongly is *not* a forum -- and Ask Fedora is less successful because it _is_ a forum which happens to have a UI which mimics the surface-level appearance of Stack Exchange.

Can you name any sites for generating documentation content that is more, or even as, successful as the Arch or Ubuntu wikis?

That isn't a rhetorical question, if there are other sites that are successful at getting community participation in generation documentation then we should definitely be looking at how they are successful.

#######

We have kind of derailed Ryan's question though, which should be answered before you look at wikis/forums/whatever.

"We really need to nail down what we want the content to be, how it is structured, and layed out before discussing any toolchain changes."

Let me rephrase it though, as his question focuses on the docs and the docs team, which IMO is wrong).

What kind of docs are the best for Fedora users?

IMO the majority of content would be short articles, straight to the point, simple language, with some basic examples.

Then I'd ask, who do we want to participate?

The barriers to entry should be low enough that the least technical members of that group should be able to participate without feeling overwhelmed.

Then I'd start talking about tools that address those requirements.

Cheers, Jeff.

I favour a wiki approach to documentation.  I also favour using libreOffice with the "Produce Docbook" output format. I wrote "This is a test of docbook output" with LibreOffice and saved the output in docbook format. This is the resulting output<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <article lang="">   <para>This is a test of docbook output</para>   <para/> </article>

Writing with WYSIWYG (What you see is what you get), is great for technical writing. As well, the markup and collaboration tools in LibreOffice are what appeals to many individuals.Translation from English to other languages  is made easier by using web services from Google, Microsoft and others.

I would also suggest you compare these two links.Fedora https://docs.fedoraproject.org/en-US/index.html%C2%A0%C2%A0%C2%A0%C2%A0%C2%A... SUSEhttps://en.opensuse.org/Main_Page Which of the two is more inviting and easier to use?  Regards  Leslie Mr. Leslie Satenstein Montréal Québec, Canada

From: Matthew Miller mattdm@fedoraproject.org To: For participants of the Documentation Project docs@lists.fedoraproject.org Sent: Wednesday, February 10, 2016 5:22 AM Subject: Re: Fedora Publishing

On Wed, Feb 10, 2016 at 10:20:10AM +1000, Jeff Fearn wrote:

You are comparing places where communities create content to a place communities publish content.

Sure, fair enough. And, yeah, kudos to Ubuntu community docs too.

...

a forum -- and Ask Fedora is less successful because it _is_ a forum which happens to have a UI which mimics the surface-level appearance of Stack Exchange.

Can you name any sites for generating documentation content that is more, or even as, successful as the Arch or Ubuntu wikis?

Well, again, Stack Exchange. Take a look at http://unix.stackexchange.com/questions?sort=frequent

What kind of docs are the best for Fedora users? IMO the majority of content would be short articles, straight to the point, simple language, with some basic examples.

+1 to both the question and answer here. That makes +2, I guess. :)

Leslie S Satenstein wrote:

I favour a wiki approach to documentation. I also favour using libreOffice with the "Produce Docbook" output format.

I wrote "This is a test of *docbook* output" with LibreOffice and saved the output in docbook format.

This is the resulting output

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<article lang=""> <para>This is a test of docbook output</para> <para/> </article>

Writing with WYSIWYG (What you see is what you get), is great for technical writing. As well, the markup and collaboration tools in LibreOffice are what appeals to many individuals. Translation from English to other languages is made easier by using web services from Google, Microsoft and others.

I would also suggest you compare these two links. Fedora https://docs.fedoraproject.org/en-US/index.html SUSE https://en.opensuse.org/Main_Page

Which of the two is more inviting and easier to use?

Regards

Leslie

*Mr. Leslie Satenstein* *Montréal Québec, Canada*

**

------------------------------------------------------------------------

*"hi Libre office can produce docbook output? That's great. I can write in my preferred editor and still produce docbook for fedora docs. Thanks for the info, I had no idea. Does it require an extension or can it natively do this? Thanks Kendell Clark"

*

*From:* Matthew Miller <mattdm@fedoraproject.org>
*To:* For participants of the Documentation Project
<docs@lists.fedoraproject.org>
*Sent:* Wednesday, February 10, 2016 5:22 AM
*Subject:* Re: Fedora Publishing

On Wed, Feb 10, 2016 at 10:20:10AM +1000, Jeff Fearn wrote:
> You are comparing places where communities create content to a place
> communities publish content.


Sure, fair enough. And, yeah, kudos to Ubuntu community docs too.

> > a forum -- and Ask Fedora is less successful because it _is_ a
forum
> > which happens to have a UI which mimics the surface-level
appearance of
> > Stack Exchange.
> Can you name any sites for generating documentation content that is
> more, or even as, successful as the Arch or Ubuntu wikis?

Well, again, Stack Exchange. Take a look at
http://unix.stackexchange.com/questions?sort=frequent

> What kind of docs are the best for Fedora users?
> IMO the majority of content would be short articles, straight to the
> point, simple language, with some basic examples.

+1 to both the question and answer here. That makes +2, I guess. :)

-- 
Matthew Miller
<mattdm@fedoraproject.org <mailto:mattdm@fedoraproject.org>>
Fedora Project Leader

--
docs mailing list
docs@lists.fedoraproject.org <mailto:docs@lists.fedoraproject.org>
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Feb 10, 2016 16:58, "Jeff Fearn" jfearn@redhat.com wrote:

On 10/02/16 20:22, Matthew Miller wrote:

...

On Wed, Feb 10, 2016 at 10:20:10AM +1000, Jeff Fearn wrote:

...

You are comparing places where communities create content to a place communities publish content.

Sure, fair enough. And, yeah, kudos to Ubuntu community docs too.

...

...

a forum -- and Ask Fedora is less successful because it _is_ a forum which happens to have a UI which mimics the surface-level appearance

of

...

...

...

Stack Exchange.

Can you name any sites for generating documentation content that is more, or even as, successful as the Arch or Ubuntu wikis?

Well, again, Stack Exchange. Take a look at http://unix.stackexchange.com/questions?sort=frequent

IMHO SE is just a web forum with voting and some fancy CSS, so I guess I +1 that :)

...

...

What kind of docs are the best for Fedora users? IMO the majority of content would be short articles, straight to the point, simple language, with some basic examples.

+1 to both the question and answer here. That makes +2, I guess. :)

Cheers, Jeff.

--

There are three factors to consider here: ease of contribution, ease of collaboration, and the quality of the resulting copy. Without a well established collaborative workflow, a very low barrier to contribution leads to low quality documentation. We have seen this with both the Fedora wiki and with Ask Fedora. StackExchange works because users aggressively cull out dupes and poor answers, and that is not happening with Fedora's sites. There is already a general expectation to not be redundant or incorrect on these platforms, and IMO that expectation is not being met. Providing the same kind of platform to the same user base with the same expectations will likely produce the same result.

This is why I advocate a git and pull request oriented workflow, and a solution built around that workflow. If you have proven that you produce quality work, it should be easy to publish directly. If you have not, it should be easy to submit those drive-by contributions for review and easy to review them. Adding someone to a FAS group so they can publish directly is not an arduous task, and with PRs demonstrating the efficacy of the contributors work, it is not difficult to decide someone should be able to do that. A solution without this gating will inevitably lead to us having this conversation again.

--Pete

On 9 March 2016 at 12:24, Dylan Combs dylan.combs@gmail.com wrote:

Is there something wrong with a moderated wiki that I'm missing? Sorry - I don't mean to be a pest here, and I had kinda given up on the thread, but it's still kickin', it seems.

A git workflow doesn't strike me as as bad, necessarily, but man it's gotta be incredibly simple and obvious how to participate. If it's simply:

1. Sign up for an account / Log in
2. Use a browser to navigate to the page/section in need of modification.
3. Press a button to enter composition mode in the browser.
4. Write content in the browser.
5. Press a button to submit pull request from the browser.

Then it seems right to me. In fact, a git style system would probably provide a nice way to share logins with ask.fedoraproject and/or karma, badges, and awards for content (which I think is crucial for elevating user privileges based on merit and whatnot). If it's more complicated than the above, I'm back to the moderated wiki suggestion. If there's a client-side application involved that isn't the browser and is somehow so simple and accessible that it can't possibly be a barrier to entry, that'd probably be ok, too.

As a point of information, that's pretty much github's editing of markdown files, though generally you need to 1.5) Create your own fork.

When saving you have the options: Commit directly to the master branch Create a new branch for this commit and start a pull request. (Learn more about pull requests.)

I've just tried on a local gitlab install and it similarly offers to create merge requests if editing a fork (but it doesn't have github's wysiwyg markdown editing, just raw text, maybe there's a plugin).

On Wed, 9 Mar 2016 07:24:21 -0500 Dylan Combs dylan.combs@gmail.com wrote:

Is there something wrong with a moderated wiki that I'm missing? Sorry - I don't mean to be a pest here, and I had kinda given up on the thread, but it's still kickin', it seems.

A git workflow doesn't strike me as as bad, necessarily, but man it's gotta be incredibly simple and obvious how to participate. If it's simply:

1. Sign up for an account / Log in
2. Use a browser to navigate to the page/section in need of modification.
3. Press a button to enter composition mode in the browser.
4. Write content in the browser.
5. Press a button to submit pull request from the browser.

Then it seems right to me. In fact, a git style system would probably provide a nice way to share logins with ask.fedoraproject and/or karma, badges, and awards for content (which I think is crucial for elevating user privileges based on merit and whatnot). If it's more complicated than the above, I'm back to the moderated wiki suggestion. If there's a client-side application involved that isn't the browser and is somehow so simple and accessible that it can't possibly be a barrier to entry, that'd probably be ok, too.

What say ye, Pete? Is there a tool you had in mind that meets those requirements?

-Dylan

Don't get the wrong impression, Dylan - I want you to have a way to participate that is as easy as you describe. A moderated and well curated wiki would be easy for you to throw content into. If you want to get started now, writing in the Fedora wiki requires only agreement with the CLA.

There are currently around twenty two thousand people that meet that requirement. To the best of my knowledge, exactly none of those people have expressed an interested in contributing 5-10 hours each week moderating a wiki. The complexity of organizing and reviewing content exists with wikis, as it does with publican docbook sites, or CMS systems like wordpress, or with a continuous integration build platform.

If you want simple submissions, the complexity must move from the submission part of the workflow to the curation part of the workflow. My position is that this complexity should be dealt with using code as much as possible. That does not mean that you cannot have a box and button in the browser, but it does mean that something different should happen with the content after you press the button, and it effectively limits new works to other users logging into a website, typing a thing, and pressing the button.

There's a bonus: some content can be generated, instead of manually written. Consider these activities:

- Provide a page on the site for each manpage provided by each Fedora pacakge. Update each page every time each package changes. - Provide a list of pacakge groups available for each supported release. For each group, describe the group's function and member packages. Update for each change. - Provide a summary of each graphical application shipped in the default Fedora Workstation install. Update this with each release. - Create usage instructions for each python library available in Fedora. Update the instructions whenever the library changes. - Maintain a package and configuration mainfest for the Atomic image. - Maintain a list of all rolekit roles, and a page describing the usage of each.

Okay, these probably aren't the things you were planning on writing. It gives you a good starting place, though; background information for the writing you *are* interested in, manpages and other packaged documentation for crossreferences, ready-made content detailing attributes of packages or images that a human isn't especially required to generate.

-- Pete

On Mar 9, 2016 12:06, "Matthew Miller" mattdm@fedoraproject.org wrote:

On Thu, Feb 11, 2016 at 11:25:24AM -0600, Pete Travis wrote:

...

collaboration, and the quality of the resulting copy. Without a well established collaborative workflow, a very low barrier to contribution leads to low quality documentation. We have seen this with both the

Fedora

...

wiki and with Ask Fedora. StackExchange works because users

aggressively

...

cull out dupes and poor answers, and that is not happening with Fedora's

This works on Stack Exchange because there's a lot of well-considered and constantly tweaked UX design focused on the community moderation side. The wiki 5 no understanding of why things are there or what they actually do.

...

sites. There is already a general expectation to not be redundant or incorrect on these platforms, and IMO that expectation is not being met. Providing the same kind of platform to the same user base with the same expectations will likely produce the same result.

Yeah, community expectations are important too. I think in Ask Fedora, the lack of a "meta" is a crucial part of the pain — and in the Wiki, maybe it's correspondingly a lack of a culture of using the Talk pages for similar purpose.

This is a tangent from your point, but what you're talking about made me realize that any new service made without a clear connection to a community communication mechanism is going to fail. (Maybe a new Hub for docs would serve? Or, less grandiose, simply prominent connections to the hyperkitty interface for this list?)

-- Matthew Miller

I'm personally content with the existing IRC+list channels for Docs meta-discussion, which fits with Hubs as I understand it. For discussion of implementation details and back and forth on WIP content, pagure issues would work - a hubs tie-in here would be cool. I'm not that familiar with Hubs beyond the metaphorical relationship to sliced bread...

The gist of my desire here is a solution and workflow that abstracts away the curating/organizing tasks as much as possible. Automatically retiring outdated content, automatically organizing content from embedded metadata, etc plus the capability to do more automatic things we haven't thought of yet. The trapdoor behind 'just do this thing that is easy to describe' has a big spiked pit of 'somebody still has to do all this work' underneath.

--Pete

--Pete

On Thu, Mar 10, 2016 at 07:50:53AM +1000, Jeff Fearn wrote:

There are tonnes of existing apps that have write, review, publish work flow built in, many of them are wikis. The fact that a lot of sites choose not to use those work flows doesn't mean the work flows don't work if you enable them.

Jeff, can you prototype a demo of a solution -- I guess wiki-based? -- that would fit our needs and wants?

On 10/02/16 10:20, Jeff Fearn wrote:

On 09/02/16 18:51, Matthew Miller wrote:

...

On Tue, Feb 09, 2016 at 12:37:58PM +1000, Jeff Fearn wrote:

...

If the goal is to get more participants, then if it's not a wiki or a Q&A forum, then you are knowingly choosing a tool that is less successful in achieving this goal.

I don't think this premise is true at all. We're talking about something like http://readthedocs.org/,

The premise is that barriers to entry are greater in tools that don't offer easy to participate interfaces like wikis, forums, and Q&A sites (which IMO are just forums with some fancy CSS).

If you published to RTD right now, which is trivial, would it affect participation in any way?

...

which is *way* more successful than most wikis.

You are comparing places where communities create content to a place communities publish content.

RTD is a place for communities to publish content they have already have; it doesn't address how those communities get the content to publish or edit & maintain it.

...

In fact, I think gardened wikis that work are the exceptions rather than the rule (Arch docs, Wikipedia, and nothing else at any scale).

Successful docs sites are also the exception rather than the rule.

I don't know how you missed mentioning Ubuntu, they are clearly the gold standard in community participation for documentation.

...

And forums? Gah! They're a nightmare and part of the problem. Stack Exchange is successful because it very strongly is *not* a forum -- and Ask Fedora is less successful because it _is_ a forum which happens to have a UI which mimics the surface-level appearance of Stack Exchange.

Can you name any sites for generating documentation content that is more, or even as, successful as the Arch or Ubuntu wikis?

That isn't a rhetorical question, if there are other sites that are successful at getting community participation in generation documentation then we should definitely be looking at how they are successful.

#######

We have kind of derailed Ryan's question though, which should be answered before you look at wikis/forums/whatever.

"We really need to nail down what we want the content to be, how it is structured, and layed out before discussing any toolchain changes."

Let me rephrase it though, as his question focuses on the docs and the docs team, which IMO is wrong).

What kind of docs are the best for Fedora users?

Yes, this is a better interpretation of what I was trying to say, thanks :)

cheers, ryanlerch

IMO the majority of content would be short articles, straight to the point, simple language, with some basic examples.

Then I'd ask, who do we want to participate?

The barriers to entry should be low enough that the least technical members of that group should be able to participate without feeling overwhelmed.

Then I'd start talking about tools that address those requirements.

Cheers, Jeff.

Charles I have experienced the same situations as you. I did achieve some wiki editing, but, felt that the documentation project's mandate and what you and I would like to do to contribute were incompatible. After two years, I still have no idea how to generate points to that website so as to be allowed to respond or contribute. I now contribute to another RPM type distribution.

I am a devoted Fedora user, beginning with Core, some 12 years ago.  I mostly resort to Googling for information and discussions pertaining to some Fedora features.  Imagine if that outside information could be merged into the reference type of Fedora documentation.

I find that there is a second gap that we users and Project Managers face.  The Project Managers respond to RedHat's business/technical requirements, and to me it appears they do so without consulting users. There are some forums on which you will find users like yourself, who can provide some ideas, but we only watch, and wait.

Regards  Leslie Mr. Leslie Satenstein Montréal Québec, Canada

From: charles profitt fedora@cprofitt.com To: docs@lists.fedoraproject.org Sent: Thursday, February 4, 2016 10:13 PM Subject: Re: Fedora Publishing

On Thu, 2016-02-04 at 17:25 +0100, Paul W. Frields wrote:

Drive-by contributions are perfect for docs (and really they're the lifeblood all open source projects would love to have).  I contend we should optimize for that, because all other contributors' lives get easier as a result -- riding the wave.

I do not want to jump in on other parts of the conversation, but this item struck a chord with me.

I was very involved in the Ubuntu Wiki Documentation efforts and looked to get involved here. Due to the apparent upheaval in that area I have stayed away - out of confusion about how to help. I also try to use ask fedora, but found that I could not make basic edits or add images to my answers until I had earned 'enough' points'.

I truly think it would be good to have a way to make the process easier for interested people to contribute.

As for the mechanism (wiki, stack exchange, etc) that is something I am not sure has a single answer. Sadly, every technical product I know of has the issue of out-of-date documentation because things move so quickly.

I would love to see some automated document life-cycle solution used to help combat the out-of-date syndrome.

Charles -- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Feb 16, 2016 21:17, "Glen Rundblom" glen@rundblom.com wrote:

Hello everyone, After reading some of the conversation about publishing for Fedora I

wanted to just make my observations known.

I am thankful and grateful to Pete, and the rest of the Fedora Docs team

for teaching me how to contribute.

As I struggle to build my knowledge of Linux, and trying to contribute

and give back to the Red Hat/CentOS/Fedora world , I learned a lot. However I did not realize how much of a time commitment in writing in doc book, fixing my doc book code, test building in publican, and then re-doing my docbook code because it does not work right on the docs site.

I am not good at it yet, but, the time overhead just for a small chunk of

content is really substantial. When I described the process of how doc writers work in Fedora, several people in my local linux users group lost interest.

I do not know what the solution is, but making docs contribution less of

a process would substantially help grow contributors. It would also increase my satisfaction of useable content VS labor (but this will hopefully improve as I get better in writing in docbook).

Where I work, and the people I encounter (users and other IT Pro's)

documentation is expected to be done via wiki. Wiki's have their problems, but it gets people putting info somewhere, and that's 95% of the battle for us.

Respectfully, -Glen

--

I also have a wiki at work for documentation. There are daily email threads with links to, or about, wiki docs because wiki pages are not discoverable, are often redundant, and sometimes conflicting. I believe this is the inevitable state of all wikis, at this point. Nobody feels the contribution process should not be easier, but I'm not enthusiastic about trading one set of problems for another.

--Pete

On Thu, Feb 18, 2016 at 08:27:43AM +1000, Jeff Fearn wrote:

The current system does not address scalibility issues, it's simply insulated from them because it is a huge barrier to entry. If you could somehow magic a lot more contributors using the current system you'd hit the exact same gardening issues as content increased and fragmented. i.e. If you get more contributors you will have to face these gardening issues regardless of the technology you chose.

Right, so, I think an important goal of the new system is to make that gardening easy -- and it just plain isn't with wikis.

Can't we just moderate the wiki?

I imagined the Docs team would be responsible for its architecture and the moderation/approval of content which would simply be open for editing submissions by anyone. That keeps the structure from decaying into the problems Pete described and it allows immediate and easy editing submissions by anyone who drives by. If immediate-feedback is a concern, we could even have it configured so that recent yet-to-be-approved suggestions appear in some immediate form that marks them as obviously yet-to-be-approved or something.

On Wed, Feb 17, 2016 at 6:08 PM, Jeff Fearn jfearn@redhat.com wrote:

On 18/02/16 08:42, Matthew Miller wrote:

...

On Thu, Feb 18, 2016 at 08:27:43AM +1000, Jeff Fearn wrote:

...

The current system does not address scalibility issues, it's simply insulated from them because it is a huge barrier to entry. If you could somehow magic a lot more contributors using the current system you'd hit the exact same gardening issues as content increased and fragmented. i.e. If you get more contributors you will have to face these gardening issues regardless of the technology you chose.

Right, so, I think an important goal of the new system is to make that gardening easy -- and it just plain isn't with wikis.

There are well gardened wikis, you have even named some, there are no sites where gardening is easy.

Cheers, Jeff.

-- Jeff Fearn Senior Software Engineer PnT - DevOps - Development Red Hat Asia Pacific Pty Ltd http://dilbert.com/fast/2004-08-17/ -- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Thu, Feb 18, 2016 at 09:08:51AM +1000, Jeff Fearn wrote:

On 18/02/16 08:42, Matthew Miller wrote:

...

On Thu, Feb 18, 2016 at 08:27:43AM +1000, Jeff Fearn wrote:

...

The current system does not address scalibility issues, it's simply insulated from them because it is a huge barrier to entry. If you could somehow magic a lot more contributors using the current system you'd hit the exact same gardening issues as content increased and fragmented. i.e. If you get more contributors you will have to face these gardening issues regardless of the technology you chose.

Right, so, I think an important goal of the new system is to make that gardening easy -- and it just plain isn't with wikis.

There are well gardened wikis, you have even named some, there are no sites where gardening is easy.

The primary hard parts of gardening, from my experience, are:

* locating where it needs to be done * handling it as a repeatable, scalable routine to avoid backlog

I am in 100% agreement with Ryan, Jeff, and Matthew (and maybe Pete I hope?) that short, focused content that addresses a specific user problem is key.

I think that eases the second problem *somewhat* -- the shorter the doc, the easier it is to jump in and garden without it becoming a huge research project. Another part of solving the second problem is a system that alerts the team there is reviewing, checking, or editing to do on a change.

However, none of these address the question of rot (which I think comes more from the first problem). Perhaps flagging an article by age so it's reviewed on a periodic basis helps. But much more important is the low barrier.

I notice that both Pagure and Github have online editing of text files. Those generate pull requests back to the people who manage the project. Hmm...

On 04/02/16 20:54, Paul W. Frields wrote:

For instance, AsciiDoc has really been embraced

FYI it is easy to convert a Publican book to AsciiDoc.

$ publican build --formats xml --langs en-US $ cd tmp/en-US/xml $ xmllint --xinclude $main.xml --output escape_xml_hell.xml $ pandoc --to=asciidoc --from=docbook escape_xml_hell.xml -o foo.txt $ a2x -f xhtml foo.txt $ firefox foo.html

Fly my pretties, FLY!

Cheers, Jeff.

On Fri, Feb 05, 2016 at 10:18:20AM +1000, Jeff Fearn wrote:

On 05/02/16 08:33, Jeff Fearn wrote:

...

On 04/02/16 20:54, Paul W. Frields wrote:

...

For instance, AsciiDoc has really been embraced

FYI it is easy to convert a Publican book to AsciiDoc.

$ publican build --formats xml --langs en-US $ cd tmp/en-US/xml $ xmllint --xinclude $main.xml --output escape_xml_hell.xml $ pandoc --to=asciidoc --from=docbook escape_xml_hell.xml -o foo.txt $ a2x -f xhtml foo.txt $ firefox foo.html

Fly my pretties, FLY!

Cheers, Jeff.

P.S. You can then use po4a to get POT/PO files from the AsciiDoc.

So for example, moving to smaller content/other tools/different markup doesn't mean losing existing content. Brilliant!

After reading all the comments so far I finally have something to say. And it has nothing to do about the technical end of producing documentation. I want to talk about people and community.

We are a community of volunteers who produce documentation. That is the bottom line. Thus, standards are not exactly something that can be forced down the throat of a volunteer. All of us come to the table with differing skill sets and backgrounds. And as a volunteer we are not really willing to learn something new or change the way we do things when there is no reward except the satisfaction of a job well done.

The real question we should be asking is how do we best make use of these diverse skill sets to produce documentation that is organized and contains great content. If we can agree that this is the real question before us then we can begin discussions on how to solve the problem. Otherwise we will be spinning our wheels and wasting valuable resources.

one solution put forward was to figure out how to accept a variety of input formats into a process that produces the output we want. Obviously some conversion of the input will need to be performed so that a common output can be maintained.

The above process would be very nice and could probably be built, but it also has a big issue. In our volunteer environment, the maintainer is usually not the original writer and their skill sets may not match. So another big question is how do we solve this problem? Do we force the maintainer to learn the document's original format? Do we perform maintenance in a common format?

I think you can see from the above discussion that we have a really tough problem to solve. And the root of that problem is the people who volunteer their time and resources. In our case, diversity of skills is the key issue. Until we can come to an agreement that this is the real problem we will never solve the technical problem. We have to design a process and a set of governance rules that solves our people problem.

Technical problems can almost always be solved, people issues are harder.

W. David Ashley

On Feb 5, 2016 09:41, "John J. McDonough" wb8rcr@arrl.net wrote:

On Fri, 2016-02-05 at 08:55 -0600, David Ashley wrote:

...

one solution put forward was to figure out how to accept a variety of input formats into a process that produces the output we want. Obviously some conversion of the input will need to be performed so that a common output can be maintained.

I think this is key. But there is something else we seem to be ignoring; we need a way to produce reasonable hardcopy output.

Much of the time you NEED the documentation you don't have access to a computer or the Internet. When you look something up a lot of the time the small chunk is very handy. But when you are in deep doo-doo you often need to be holding a piece of paper in your hot little hands. Even when things haven't totally gone south, a lot of processes leave you without access part of the time, and you either need to scribble down the next steps or have a good memory.

And there is another dimension that could help (and maybe this again has to do with conversion); it is handy if hardcopy output is dense. Even our current model produces documents that perhaps focus more on form than function. That is, they look nice but contain a lot of wasted space. For the hardcopy output, you really want a minimum number of pages in preference to looking pretty.

Man pages are pretty nice this way, although when they get a little longer they tend to become more opaque. And the main problem with man pages is that you need to know the answer ahead of time. One very nice feature of man pages is that you can print them and get something usable.

Online documents almost want to be the opposite. You would like plenty of whitespace to help organize and highlight the content. But when you try to print a wiki you get a huge pile of useless paper.

We were pretty close with translation of the wiki to docbook, but mw- render wasn't kept up to date, and not a lot of folks used it because it only did a 95% job. I guess whatever we have has to be polished.

Stickster mentioned that we should look to existing tools, and I like that idea, *IF* we can find something that works. Our history is littered with tools that looked like they mostly did the job but were eventually discarded because they couldn't really do what we expected.

Someone earlier mentioned a git-based wiki sort of tool that sounded close, but that appeared to be closed source so I didn't look too hard, but given all the expectations we have, I'm skeptical.

On the flip side, as David mentioned, we are a group of volunteers, and as such, tend to be kind of fluid. I have little doubt that Pete or myself could grok together something that works, but then even if we are still around a few more releases, real life will interfere with needed maintenance.

Not sure of the answer - lots of dimensions. But don't loose sight of the features we already have when looking for new ones.

--McD

hmm... I'm taking two solid 'requirements' bullet points from this:

- Accommodate long and short form works In the tooling context, I read this as needing a document table of contents, and multipage document support, in addition to a site-global toc for single page articles. This is a must have to use the existing books. - Ensure the capacity for alternative output formats.

And perhaps a nice-to-have: when rendering ie pdf or epub, provide the capacity for styling/templating/structure that's more appropriate for that format, instead of ie 'print webpage to pdf'. That's probably a long term thing, but anything with modular output capability makes it possible.

--Pete

On 2/6/2016 3:22 AM, Paul W. Frields wrote:

On Fri, Feb 05, 2016 at 10:40:54AM -0500, John J. McDonough wrote:

...

On Fri, 2016-02-05 at 08:55 -0600, David Ashley wrote:

...

one solution put forward was to figure out how to accept a variety of input formats into a process that produces the output we want. Obviously some conversion of the input will need to be performed so that a common output can be maintained.

I think this is key. But there is something else we seem to be ignoring; we need a way to produce reasonable hardcopy output.

Much of the time you NEED the documentation you don't have access to a computer or the Internet. When you look something up a lot of the time the small chunk is very handy. But when you are in deep doo-doo you often need to be holding a piece of paper in your hot little hands. Even when things haven't totally gone south, a lot of processes leave you without access part of the time, and you either need to scribble down the next steps or have a good memory.

[...snip...]

I disagree that hardcopy is a priority. Even if your laptop, desktop, or server has gone south and you can't connect, far more than likely than not you have another connection in your hand, called your phone (or tablet). Hardcopy is unnecessary. This isn't to say we shouldn't support printouts, but they should certainly not be a priority or blocker. Mobile friendly makes more sense as a requirement.

...

Stickster mentioned that we should look to existing tools, and I like that idea, *IF* we can find something that works. Our history is littered with tools that looked like they mostly did the job but were eventually discarded because they couldn't really do what we expected.

Precisely why I think it would be good to get content services folks involved. They already have the same needs and the resources to help develop requirements. If Fedora Docs surveys and/or develops something they can't use, chances are not good that we could get additional contribution there.

"hi I'll just point out that not *everyone* has a phone or a tablet. I have neither. Having said that, I agree that fedora should be mobile friendly, as much as possible. I will caution though that it seems that most people have grown to assume and take for granted you have either a phone or a tablet, and can download an app to do the job. I agree we should be as mobile friendly as possible, but shouldn't assume you have that option available. Now that I've put my foot in my mouth, does anyone know if there are any special steps that need to be taken to make the "mobile" version of fedora's sites accessible, or will they just work like the standard ones do?

Thanks Kendell clark"

On 2/5/2016 2:32 PM, Pete Travis wrote:

On 02/05/2016 08:55 AM, David Ashley wrote:

...

After reading all the comments so far I finally have something to say. And it has nothing to do about the technical end of producing documentation. I want to talk about people and community.

We are a community of volunteers who produce documentation. That is the bottom line. Thus, standards are not exactly something that can be forced down the throat of a volunteer. All of us come to the table with differing skill sets and backgrounds. And as a volunteer we are not really willing to learn something new or change the way we do things when there is no reward except the satisfaction of a job well done.

The real question we should be asking is how do we best make use of these diverse skill sets to produce documentation that is organized and contains great content. If we can agree that this is the real question before us then we can begin discussions on how to solve the problem. Otherwise we will be spinning our wheels and wasting valuable resources.

one solution put forward was to figure out how to accept a variety of input formats into a process that produces the output we want. Obviously some conversion of the input will need to be performed so that a common output can be maintained.

The above process would be very nice and could probably be built, but it also has a big issue. In our volunteer environment, the maintainer is usually not the original writer and their skill sets may not match. So another big question is how do we solve this problem? Do we force the maintainer to learn the document's original format? Do we perform maintenance in a common format?

This would be an additional feature to add to our checklist when vetting a solution: dynamic conversion of the *input* document to allow maintainers to contribute to existing docs in the format of their choice. Atlassian Confluence is the only solution I'm aware of - anecdotally - that does this, and it's not an option for us. It would be nice to have, but if a writer wants to own an iteration of a document that's currently written in asciidoc, and they really would prefer to edit in docbook, I think it should be reasonable for that writer to perform their conversion outside of the buildsystem.

...

I think you can see from the above discussion that we have a really tough problem to solve. And the root of that problem is the people who volunteer their time and resources. In our case, diversity of skills is the key issue. Until we can come to an agreement that this is the real problem we will never solve the technical problem. We have to design a process and a set of governance rules that solves our people problem.

Technical problems can almost always be solved, people issues are harder.

W. David Ashley

The current organizational process would be something like this:

1. Needs are discussed
2. Solutions are suggested that meet some or all of the needs
3. Needs not met by a proposed solution are re-evaluated
4. A sufficiently adequate solution is planned in detail, openly
5. The solution is implemented, or not, by either clear consensus or vote.

I don't see governance issues coming in until the last step, and we're hovering somewhere between step 1 and step 1.5. I didn't find any prebaked solutions that fit the needs I felt were important, especially with regard to CICD functionality, so I started creating one with mostly prebaked components. This doesn't preclude concurrent work of other solutions.

Otherwise, I'm not sure what kind of organizational or policy type changes would help; can you elaborate?

-- Pete

"hi Speaking from someone who has contributed to fedora's docs before, the process isn't easy but it isn't difficult. I've been meaning to apologize for the tone of my message earlier. I got to thinking about it and it sounded a little too demanding when I really thought about it. I'll rephrase it a bit. I want to become a member of fedora's docs community, so I can maintain the accessibility guide, which is mostly up to date, but there are sections that sound a little too ... stiff and formal. If we could settle on a format I could understand, that would make my job easier, but I am willing to write in plain text or odf and send this to someone for conversion if necessary. Some form of markdown would be nice, since I know a little about it and headings, lists, etc aren't too difficult to make. Does publican understand markdown? I really don't understand the tool that well, but I believe it takes a config file and xml, and uses that to convert the docs into various other output formats (pdf, html, txt, epub?) Pete is right though. This is a volunteer effort, so you can't expect everyone to settle on a rigidly defined set of standards. A loose one might work though. It's also worth pointing out that whatever solution we use must be free software. Publican is, I think. I'm a little confused. Are we thinking about switching software we use to compile the docs? Thanks Kendell clark"

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org

On Mon, Feb 08, 2016 at 09:34:35AM +1000, Jeff Fearn wrote:

On 02/05/2016 11:34 PM, Dylan Combs wrote:

...

(2) tooling that worked like a git/pull-request model?

As a developer I am really opposed to inflicting git's pull/request work flows on Humans. IMO docs and code have a highly divergent set of attributes and what makes git good for code doesn't help at all with docs, in fact the complexity of git work flow is just a barrier to entry for a lot of potential docs contributors.

Elsewhere I mentioned online editing in a git repo (which could be made transparent to a user). The user edits in a web browser, and doesn't worry about the pull-request mechanics. I'm not married to that by any means. But it seems to me that someone clicking a link, editing in a text entry form, and hitting a "Save" button without having to do any other work is a pretty low barrier and worth aiming for.

On Feb 18, 2016 11:05 AM, "Pete Travis" me@petetravis.com wrote:

On Feb 18, 2016 9:27 AM, "Paul W. Frields" stickster@gmail.com wrote:

...

On Mon, Feb 08, 2016 at 09:34:35AM +1000, Jeff Fearn wrote:

...

On 02/05/2016 11:34 PM, Dylan Combs wrote:

...

(2) tooling that worked like a git/pull-request model?

As a developer I am really opposed to inflicting git's pull/request work flows on Humans. IMO docs and code have a highly divergent set of attributes and what makes git good for code doesn't help at all with docs, in fact the complexity of git work flow is just a barrier to entry for a lot of potential docs contributors.

Elsewhere I mentioned online editing in a git repo (which could be made transparent to a user). The user edits in a web browser, and doesn't worry about the pull-request mechanics. I'm not married to that by any means. But it seems to me that someone clicking a link, editing in a text entry form, and hitting a "Save" button without having to do any other work is a pretty low barrier and worth aiming for.

-- Paul W. Frields

The system I've been working on is intended to address this by

periodically querying pkgdb, which maps F$n to rawhide, prerelease, brabched, current release, previous release, and eol iirc. The system then maps git branches to release statii so only content from ie current and previous release are propagated to the user. This is similar to the dist-git paradigm, except that release branches are not automatically created in content repos; this way, expiration of content is automatically offloaded to the CICD process unless maintainers take explicit action to branch and update their content for a given release.

Some of this code exists, but could use more polish. I'm currently

trying to set it up so the branch mapping can live in the content repo, and the repo's build process (to a reasonable extent) can be defined in the same place as the content.

And yes, pagure compliments this method nicely, especially the online

editing feature, which iirc pingou began to implement after I discussed some of the above with him.

--Pete

Whoops, quote fail, this was in response to Paul's immediately preceding post regarding wiki gardening.

--Pete

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256

On 02/05/2016 10:33 PM, Paul W. Frields wrote:

On Fri, Feb 05, 2016 at 10:18:20AM +1000, Jeff Fearn wrote:

...

On 05/02/16 08:33, Jeff Fearn wrote:

...

On 04/02/16 20:54, Paul W. Frields wrote:

...

For instance, AsciiDoc has really been embraced

FYI it is easy to convert a Publican book to AsciiDoc.

$ publican build --formats xml --langs en-US $ cd tmp/en-US/xml $ xmllint --xinclude $main.xml --output escape_xml_hell.xml $ pandoc --to=asciidoc --from=docbook escape_xml_hell.xml -o foo.txt $ a2x -f xhtml foo.txt $ firefox foo.html

Fly my pretties, FLY!

Cheers, Jeff.

P.S. You can then use po4a to get POT/PO files from the AsciiDoc.

So for example, moving to smaller content/other tools/different markup doesn't mean losing existing content. Brilliant!

It's even better than that, it means once you pick a tool it's not even much of an effort to convert to a format it can import or use.

Cheers, Jeff.

- -- Jeff Fearn Senior Software Engineer PnT - DevOps - Development Red Hat Asia Pacific Pty Ltd http://dilbert.com/fast/2004-08-17/

On Feb 5, 2016 10:25, "Karsten Wade" kwade@redhat.com wrote:

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

On 02/03/2016 09:49 AM, Pete Travis wrote:

...

FWIW, I'm feeling motivated to work on the replacement this week, we should get together and whiteboard it if you're still interested in getting involved.

Keep us in the loop on the CentOS side, we are still deeply interested in collaborating on toolchains (at least) and possibly upstream-downstream looping of content.

• • Karsten

---

Karsten 'quaid' Wade .^\ CentOS Doer of Stuff

I'd lost track of this, actually, thanks for jumping in. Can I catch up on the tooling, gsoc project, etc from the centos-docs list archives alone, or are there better places to look?

--Pete