Foie Gras

What is it?

Fois Gras is a temporary name for the new help system editor that ProjectMallard will include. This isn't an official page. For now, it's more a general outline of things I'd / we'd like to see in such an editor.

Use Cases

There are 2 main use cases considered here:

  • The ninja stealth method
  • The hard grind method

Ninja Stealth

We (the doc team) want to encourage people to get into doc writing. One way in is to go through the gdp, sign up to mailing lists, read the style guide etc. This is a long, boring process that people detest (and no-one does).

The other, more exciting way (using wikipedia as a basis) is to press the "Edit" button, make you're change and its done. We want to encourage this. Not only will we get more quick-fixes, but some contributors may even stick around.

Therefore, we want Foie Gras to provide an environment to get in, make a change and get out quickly. It would also be easy to submit the changes to the gdp.

Hard Grind

These are our core writers. They're the ones that sit down and rewrite huge chunks of documents to reflect reality. They're the ones that have really gone through the process of learning details of how the gdp works and are on the mailing lists. We want Foie Gras to be comfortable for them too.

Basic Premises

Foie Gras will at a minimum have:

  • Tight integration with the help browser (Yelp). It will allow viewing of final pages easily

  • WYSIWYG layout. The details of the XML will be hidden from the user. They don't need to care if you're using a <code> tag or a <literal> tag. Of course, Mallard Markup won't need these distinction (or if it does, I'll slap shaunm), but the principle remains the same

  • shaunm mentioned about the ability to have threaded comment conversation within Mallard. These should be easily accessible in Foie Gras
  • Tight integration with the meta data system. Allowing generation and editing of meta data files easily

Would be Nice Stuff

The above is a checklist of absolutely essential (IMO) features. This section gives some of the "It would be fantastic to have these" blue-sky ideas that have been circulating in my head recently.

  • Integration with SVN / CVS. If a doc writer gets permission to commit, why make them resort to the command line / finding the source directory in nautilus / whatever else? One button: "Commit". Ask for their password. Commit. Easy.
  • For those that don't have CVS / SVN access, the commit button packages the changes in a nice patch file and mails it to bugzilla / a mailing list
  • Translator mode
    • The reduced version: Split the window in 2. On top, the original (C locale) translation. On the bottom, the translation section. Keeps formatting and stops translators thinking about XML tags.
    • Full blown version: Integrate with i18n status page. Get the latest pot file. Use that as basis for translation. Show statistics on percent translated etc.
  • Review mode. For dealing with patches. Loads in original file and patch. Shows differences etc. in easy to see way. Combined with commit button, could be very powerful
  • Full-blown "Start a new Project" that will create the needed directory structure, and needed files
    • Either edit the configure.ac and top-level Makefile.am to add docs to it
    • Or: Instruct the writer how to do this
    • Ensure these changes are committed / added to the patch
  • Treeview of sections in a doc and how they're linked

Other Stuff

Random assortment of other comments and such that aren't really user-features, but things to think about and ponder.

  • Undo / Redo. From experience, this is difficult to wedge in. It should be there at the start
  • Tomboy-style saving. No need for user to save files. Done automagically. Saves hassle when submitting patches
    • Not sure about this. I find it quite easy to start rewriting a bit, and at some point make such a mess of it (just the words, not the XML) that I need to revert. I know there's a wider idea across GNOME to go this way, but I'm not sure we should be the trailblazers - Joachim

  • The translation mode couldn't be used as full translation software. It relies on context and the doc being available. Could we change this, make it act as a full translation solution? Maybe nice for translators?

  • The App should be written in python, as the Fearless Leader proclaimed. This makes it shiny to maintain and code in the first place
  • Would need to be able to handle patch files and po files, if support is added
  • Spellchecking should be included by default
  • Easy access to the Style Guide, particularly the Recommended Terminology list. Should be easy to check if a word appears in it, eg 'Choose', 'Launch' and get its entry if so.

Use Cases Revisited

Now that's down, it's time to look at the test cases again.

Ninja Stealth

Provided the app starts quickly and can quickly parse documents / find chunks of text, the ninja user should have very little problem doing a quick fix as needed. The commit button would allow them to propagate the fix back to us. The reviewer mode allows for quick review of the patch and committing. User is happy to see their contribution accepted (via a nice reply email) and continues fixing small things. Maybe they'll eventually join us and get into more serious work.

Hard Grind

Right now, these people (okay, person) is dealing with lots of verbose XML. They don't like XML. They want to write about the software, not worry that all their tags are closed properly. The WYSIWYG nature allows them to do this. Built-in spell checker allows them to easily check for silly errors. The commit button also allows them to get their work done quickly without worrying about finding the right folder and committing. The reviewer mode allows them to quickly assimilate changes from others and produce better docs.

Translators

Translators are happy because they're always happy. More importantly, without all the XML to deal with (do po files include XML?), they can translate much easier. They can see the context of the translation much easier. More docs get translated.

In the End

I'm sure I'll add more to this slowly, but that's a start for now. Comments very welcome.

Comments

ThomasHarding

  • In addition to wysiwyg mode, adding coloreds, user friendly named start and end tags (something like |=> <=|, with text instead of equal sign) will be nice

  • In DocumentationProject/Feedback, I added zebra indexing engine integration. It will be nice, if included in Yelp, to re-index after editing

  • For future versions, maybe add the ability to write xml templates representing custom DTDs, and ability to use them as "mode". eg, a mode 'failure event' with XML template written on 'failure' DTD. XSLT job would be left to the documentation server. To be clear: I written at job a very simple DTD and XSLT stylesheets plus Makefiles & scripts to transform "failure events" XML documents collection as a single docbook one, and I think it is general use :).

Projects/ProjectMallard/FoieGras (last edited 2013-12-03 19:41:23 by WilliamJonMcCann)