From Fedora Project Wiki

Revision as of 15:56, 3 March 2015 by Pmkovar (talk | contribs)

Workflow

Brian (bex) Exelbierd (https://lists.fedoraproject.org/pipermail/docs/2015-February/016037.html):

Our workflow needs to meet some goals:

  • Infrequent contributors and drive-by contributors should have the easiest possible entry to the documentation process.
    • Pete Travis: We can enable truly drive-by submissions with mechanisms like concise, dedicated workflow documentation, bz or email templates, review queues, etc. Making fire-and-forget behavior more easy is a bonus of having an active community with a clearly established workflow, not something we should explicitly model the tooling and workflow to accommodate.
  • Users at every level should have the most flexibility possible in how they do their individual work. This means that the minimum number of requirements are set.
    • Pete Travis: Some coverage of recommended methods would help out new contributors a lot.
  • Content that doesn't change from release to release should easily roll forward. Content that does vary from release to release should be able to be easily segregated and maintained. Content that has only minor variations from release to release should be able to easily be created across multiple releases.
  • When necessary content should be able to move quickly from creation to publication (i.e. CVEs). However, the process should also easily support allowing content to be held for future releases or held indefinitely pending review/conversation/revision.
  • Documentation needs to be able to move cleanly from step to step in a process. It should not be ambigious what content is in which step. This also means that unfinished work should be segragated both from finished work and other unfinished work.
  • Each step should be optimized to have the least amount of friction for it's highest consumption users or to create patterns of desired behavior through friction reduction.
  • When a trade-off has to occur, complexity should be absorbed by the toolchain first and users in later steps second. This is based on the idea that there are fewer users impacted in later steps.
  • Internationalization should not be a blocker for the English language release. Internationalization in one language shouldn't block another language.

Steps

(cut n paste from https://lists.fedoraproject.org/pipermail/docs/2015-February/016037.html)

  • Creation: The creation of new content or editing of existing content. Included in this step is any SME or language review.
    • Steps
      • Creation - self explanatory
      • Review - an optional review by peers or SMEs for technical and language attributes. We need to decide if we require this. I believe that we should request it of new writers but not of experienced writers.
    • Output: An easily manageable set of content changes or additions that can be readily identified for processing in the next stage.
  • Consensus: The decision about whether completed content is to be published and if so, for which version. This is optional, however, I believe that we should have a small group of people who are empowered to move content to publication. I do not believe every writer should have this ability. I also don't think that this is the same as reviewing. We can combine them, but that creates a lot of work for these people.
    • Steps
      • Approval
    • Output: A clearly identifiable version of a document that consists of only publishable, complete content.
  • Publication: Previewing content to verify it renders well and delivery to final location for usage by consumers. This can theoretically be almost 100% automated.
    • Steps
      • Staging - placement of completed and approved documentation for visual review
      • Publication - making completed and approved documentation available to consumers
    • Output: Content delivered to consumers.
  • Internationalization: Translation and transformation for non-English speaking audiences.
    • Steps
      • Internationalization - self explanatory
      • Staging - Internationalized versions need to be able to be verified by a qualified person
      • Publication - this can use the same publishing mechanism as English
    • Output: Content delivered to consumers.

Personas

The following section is about personas; use cases and user stories to target documentation on.

General

For every Fedora flavor there are some general personas that can be used in all categories:

Case 1: Technical Tony In this case, Tony is a certified IT professional who has much experience as well as knowledge. He will be using Fedora for either work or home and will appreciate getting solutions that provide a greater depth of knowlege.

Case 2: Novice Ned Ned is not so experienced. This may be his first installation. Ned will require step by step instructions so he does not get frustrated. Ned will not be interested in VMs unless he is also Converted Carl

Case 3: Converted Carl Converted Carl is either trying or has moved to Linux from Windows or is going to be installing a Fedora VM on his windows machine. Carl may need some translation of terminology. Carl may be either Novice Ned or Technical Tony, but he is unfamiliar with Linux terminolgy and commands.

Note: Fedora Marketing had a user story project, but there is no documentation on what happened with it and so far no one remembers it.

Workstation

(cut n paste from [1])

Target Audience

General:

Programming Environment: web languages and tools, open source databases, IDE, Compilers, debug tools, performance monitoring

Desktop apps should be sufficient to make this system the user's only computer.

Case 1: Student

Engineering/CS student who needs a personal system for software classwork and personal projects. Software class work may require particular tool chain versions. Tries out new versions of open source applications when released. Uses computer to play games. Ability to play 3D games from commercial publishers distributing games for Linux. Multiple developer environments i.e. school standard for class work, latest tools for personal use.

Case 2: Independent Developer

Personal development system for an independent software developer doing contract work or developing apps for a new opportunity.

Desktop Apps: Up to date desktop with email client, browser, productivity suite, messaging, and a complete set of desktop apps and utilities. Desktop apps should be sufficient to make this system the developer's only computer.

Generally a single development environment with the latest web development tools.

Easy to configure Virtual Machines for testing software.

Case 3: Small Company Developer

Software developer working on an individual project or coordinated small team. DevOps.

Generally a single development environment with the latest web development tools. Easy to configure Virtual Machines for testing software.

Testing in local VMs and on dedicated testing systems.

Case 4: Developer in a Large Organization

Software developer working on a large, coordinated project in a large organization.

Support for enterprise login. Multiple developer environments i.e. current project and maintenance work on older projects. Testing typically on a target system in a testing lab.

Other users

While the developer workstation is the main target of this system and what we try to design this for, we do of course also welcome other users to the Fedora Workstation. In fact, many of the changes and improvements we expect to implement for developers will be equally beneficial to other user segments. For instance our plans around multi-screen handling and improved terminal functionality should also be highly beneficial to a system administrator. Or the work we are doing to provide a high performance graphics workstation would be useful to people who want a Linux gaming PC. Or a student who just wants a system with a productivity suite to write papers will of course get benefit from the fact that we do ship a good productivity suite. We will welcome feedback and requests from all our users and try to accommodate it, as long as it doesn't negatively impact our developer target group and we have people available who have the time and ability to work on the requests.

Server

Cloud

Environments and Stacks

General

The target audience are members of the Fedora community who develop, test, package and deploy software for or on Fedora. This includes deploying and running a number of applications written in different languages, application development using different language stacks and their versions, building, and language-specific and distribution-specific packaging.

Personas

(cut n paste from [2])

Persona #1: Alan the Big Data analyst Alan is a Big Data analyst and member of the Fedora Big Data SIG. He uses a number of applications written in different languages to perform the data analysis. He wants to focus his time and effort in the application and the actual data analysis. He want to minimize the time and hassle spent obtaining, compiling, packaging and maintaining the applications that he needs. The form of packaging (rpm, deb, npm, other) isn't as important to him.

Problem statement: Currently, there is a lot of hassle and pain in dealing with non-primary (i.e. C/C++, Python, Perl) language stacks in Fedora. Although Alan wants to focus his time in the application and the actual data analysis, he too often finds himself spending time managing the language-specific toolchain needed by the application.

Cause #1: The upstream application authors usually assume that any developer would just be using the language-specific packaging ecosystem rather that also taking into account the downstream distribution-based packaging and dependency management systems. This is a problem since there are many differences between language-specific packaging ecosystems and the Fedora way of packaging software.

Cause #2: Many upstream applications use very brittle versioning. In other words, each application expects the user will be able to have its particular versions of the runtime, compiler and libraries available.

Example #1: Applications written in Scala require different versions of Scala, some need v2.9 and some need v2.10. Although Fedora could provide both versions in the same release (via SCLs or by manually maintaining two Scala packages), they would both need to be resolvable via Apache Ivy, rather than just providing both binaries, "scalac29" and "scalac210".

Example #2: The version of Jetty in Fedora does not work with Java 6 and the Apache Hadoop upstream isn't ready to abandon Java 6 yet. So the Big Data SIG ends up maintaining a patch to Apache Hadoop for Jetty 9 that will live purely in Fedora for quite a while to come. Although this could be worked-around by using compat packages for Jetty for a couple of Fedora releases, it just hides the fact that there is a mismatch in expectations between Fedora and upstream application authors.

Example #3: Node.js has its package/dep management tool available in Fedora, but very little of the language ecosystem / base libraries are packaged and available in Fedora.

Possible solution: Fedora would need a way to provide language-specific ecosystems in a way that aligns with how these language itself are used and applications written in them are developed and distributed.

Persona #2: Student or Corporate developer needing multiple development environments Billy is a CS student with multiple assignments that need different development environments/stacks to build. Bob is a corporate enterprise developer who is both developing new applications using the latest technology stacks while also maintaining older software releases that use older libraries and tool chains.

Problem statement: While they can setup different OS's or environments in separate virtual machines, it is a lot of work and wastes a lot of disk space and time. Being able to install multiple environments or versions of stacks in the same Fedora instance and switching between them on a per-project basis would be much easier and more efficient.

"What can we do to get Fedora contributors writing?"

pmkovar's notes from Flock 2014 in Prague:

  • Many developers and other contributors strongly prefer not to use xml-based formats for writing documentation
  • They say DocBook is hard to learn, too complex, and it's xml
  • Markdown is a big thing nowadays, also AsciiDoc and restructuredtext
  • Many prefer to use publishing services such as https://www.gitbook.com/ or https://readthedocs.org/
    • They are easy to set up and use popular tools such as git as part of the toolchain
  • Contributors often resort to wiki but wiki content is hard to maintain
Retrieved from "https://fedoraproject.org/w/index.php?title=Docs_Project_Focus&oldid=405196"