Docs Project Focus

Workflow

Moved to [1] to focus this page on Personas.

Contribution Model

Currently almost all documentation work is initiated by a member of the docs team, with the majority of exceptions coming from maintenance requests (via bugzilla tickets) from readers.

A model where Docs provides a pipeline for content would allow interested parties to request content and participate at any stage of content development. This might be best demonstrated with a hypothetical:

Special Interest Collaboration

Andy is a Fedora contributor, and uses Fedora to operate his 3D printer. He knows that Ambassadors often bring 3D printers to display at events, and that the type of user that hacks on 3D printers is the type that could use Fedora.

While Andy sees the need for tutorials about 3D printing with Fedora, he has no documentation experience. He's willing to help write, and knows others that would too, but needs some help with the writing. He likes the idea of short articles that he can compose while working with his printer, but doesn't want to learn docbook; his primary goal is helping people use 3D printers, not learning documentation tools.

Since there's an opportunity for many articles, the Docs team creates a new fedorahosted repo for 3D printing content. The repo comes with https://pagure.io/ , and Andy and the docs team work together to figure out some articles that could be written for it. An issue in pagure is created for each article idea, and Andy writes out some tutorials. Docs contributors find the open tickets and write tutorials too, or help Andy improve his copy.

Each tutorial is presented in a single plain text file in ReStructuredText format. It's easy for Andy and his fellow 3D printing enthusiasts to pick up, and they quickly develop a set of articles. After the content passes editorial review, it's added to the publishing system.

The publishing system reads each file in the repo. The files contain metadata that defines how they fit into a menu structure, and are in a format that the publishing system knows how to render. Each time a commit is made, the affected files are rendered to html. The publishing system then rebuilds the menu structure. If the commit was made in master, the draft site is automatically updated. If the commit was made in a release branch (F<n>) changes are validated and published for that release.

Personas

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

Overall Personas (used instead of product level personas)

Experienced Ed - Ed has used linux/unix systems in the past. He is comfortable with the shell prompt, has an editor of choice and is used to installing and configuration software. Ed is usually a cut-and-paste style programmer. So he needs things outside of basic system administration spelled out. When writing for developer forcused products, Ed is considered to be a capable programmer with mid-level skills who has limited system administration experience and needs things spelled out.

Converted Carla - Carla has the same skills as Ed, but for a non-Unix/Linux platform (Windows/Mac/etc.). She needs comparisons drawn, where appropriate and detailed steps but not explanations of functionality where not appropriate. When writing developer focused docs, Carla should be considered a mid-level programmer from a different programming paradigm (i.e. non-object oriented program when reading about OO).

Promising Petra - Petra is new to having to think about how her computer works. She is an experienced application user, but has never really learned all the short cuts or alternate ways to get things done. She tends to stick with the first application she got working for a task or else uses whatever her friends use. She needs detailed explanations of why and how things work, not just a list of steps to make it work. She is smart, just not experienced. She shows a lot of promise. When writing developer focused docs, she is considered a non-programmer who has a promising future.

General (original)

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 [2])

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

Case 1: Connected Cathy

Cathy has a spare computer, and she's installed Fedora Server on it. She uses the computer to store files and media with her family, and as a backup target for their other computers. Impressed with the variety of software on Fedora, Cathy enjoys setting up new services on the server to improve her quality of life.

Case 2: Blogger Bobby Bobby is a social media whiz, an SEO wizard, a cross-linking virtuoso. His network of interconnected blogs and social media accounts drives search traffic, hard. Bobby uses the variety of blog and CMS solutions in Fedora when creating responsive marketing strategies for his clients.

Case 3: Sysadmin Sal As the most open-minded member of a small enterprise's system administration team, Sal takes his passion for cutting edge open source technology to work. The system orchestration tools in Fedora help Sal efficiently perform routine administration tasks. When he has ideas for new things to try in his organization, he can use Fedora Server to quickly implement a proof-of-concept.

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 [3])

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
  • Lightweight formats are often missing semantic support and/or are based on non-topic-based formats
  • http://blogs.gnome.org/shaunm/2014/11/13/ducktype-a-lightweight-syntax-for-mallard/ could be an answer
• 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