Contact for managing Fedora documentation?

[David O'Brien]

Comments inline...

Karsten Wade wrote:
> On Fri, Jan 16, 2009 at 10:31:54AM +1000, David O'Brien wrote:
>   
>>>   
>>>       
>> I'm working on a project that currently produces a community version and  
>> an Enterprise version of both the software and the documentation. The  
>> community version of the documentation is written and maintained on a  
>> wiki, and the Enterprise doc using DocBook xml. Being the only writer on  
>> the project means the community version of the doc is always out of date  
>> (I focus on Enterprise doc). This is a new project and community  
>> engagement is still developing. Maintaining both versions of the doc to  
>> keep up with the software is not possible for a single writer, and quite  
>> frankly not desirable. I'm researching how I might develop all of the  
>> doc in a single language (DocBook xml) and deliver it to both  
>> destinations using publican.
>>     
>
> One of the reasons we embraced the wiki is because it greatly
> increased the community contributions.  Be aware that limiting source
> to DocBook XML also limits the number of contributors.
>   
This is one of the concerns that has been raised. We'd like to find a 
workable middle-ground, where potential contributers are not dissuaded 
by the requirement to learn or use a specific language, but neither are 
maintainers, editors, etc., bombarded with content in so many formats 
that excessive time is spent in conversions.
> This is of course without the Magic Grail that we all want -- an easy
> way similar to a wiki or wysiwyg-via-WebUI that reads and writes to
> valid DocBook XML.
>   
We need to be careful with "valid DocBook XML". What is valid for one 
brand in publican may well not be for another brand (this is my 
understanding - maybe Jeff can clarify). OOo may also output "valid 
XML", but it will fail to build using the RedHat brand. However, I 
understand the sentiment; the ability to write in <my fav. language> 
using <my fav. editor> and being able to output xml suitable for the 
brand and toolchain we're using would give me warm fuzzies. :)
> In the meantime, by moving to stand-alone repositories for each guide
> on fedorahosted.org, it pushes more in tools and decision making to
> the individual contributor teams.  It's really easy for each guide to
> set its own policy on contributions and processes for the canonical
> source.
>
>   
>> I found a bunch of info on the website about community contributions and  
>> the use of WikiText, OOo, plain text, etc., if they weren't comfortable  
>> with the idea of using xml. I'm looking into whether supporting  
>> contributions in a wide range of formats is feasible.
>>     
>
> It takes a team, in our experience so far.  Some of what you read is
> outdated; we're busy working on renaming, categorizing, and cleaning
> up that content.  In general, we support:
>
> * Wiki-only for shorter how-to/tutorials maintained inside and outside
>   of Fedora Docs Project.
>
> * Wiki that gets converted to XML when it's ready for translation
>   (Release Notes does this, several other guides have undergone this
>   transition.)  In this case, usually each version is worked via the
>   wiki first.
>
> * DocBook XML-only content (Installation Guide, Security Guide).
>   These are full-length books that are not worth pushing back and
>   forth to the wiki.  The wiki is lossy; you lose contextual meaning
>   to the mark-up.
>   
We're considering a mixture of this. We envisage an area on the wiki 
where contributers can submit how-tos, examples of how they solved a 
particular issue or a configuration that they used. If it's something 
that is suitable for Enterprise doc (and not, for example, how to 
configure unsupported hardware/software to work) then we would convert 
it to DocBook. At present we only have full-length books, and pushing 
back and forth between the wiki and DocBook is really not an option.
>   
>> I didn't determine from what I read at what point contributions are  
>> reviewed. (I didn't read the whole site, of course, just looked for the  
>> important bits.) Are reviews performed on WikiText, converted DocBook,  
>> elsewhere? How do you determine who can review and approve docs? How do  
>> you manage docs that have been submitted, converted, and published? Are  
>> edits/updates performed in WikiText and reconverted?
>>     
>
> Probably the best overall page, still sure to have some inaccuracies:
>
> https://fedoraproject.org/wiki/DocsProject/WorkFlow
>
> 1. Group collaborates on wiki content:
>
>    * Beats for Release Notes are technology specific sections to be
>    included in larger chapters.
>
>    * One chapter per wiki page for guides written on the wiki.
>
> 2. Content is ideally edited as it is written.  Writers learn as they
>    go how to improve their writing.  Editors don't save all the work
>    for the end.  All this work happens in the wiki.
>
> 3. When content is ready for translation-then-publication, it is
>    converted to DocBook XML in either the fedora-doc-utils or publican
>    toolchains.
>
> 4. Translated and base-language versions are published on
>    docs.fedoraproject.org.
>
>   
This might work for the smaller contributions from the community (in my 
project) but not for the large books (as mentioned above). The doc group 
basically consists of me, with draft contributions from developers and a 
(very) few community members.
>> What degree of sharing occurs between Fedora and RHEL documentation (if  
>> any)? How is this handled?
>>     
>
> Historically there has not been any, save an occasional release note.
>
> To catch an opportunity like this, someone needs to be willing to lead
> the effort on the document.  This means trading writing and editing
> for project management, growing trust in others to do the write/edit
> work.
>
> There has to be an upstream somewhere that we can use.  One method is
> to put the upstream content inside of Fedora.  It is then usable by
> downstreams such as RHEL.  This has not happened so far.
>
> Currently, there are several guides available or soon available as
> stand-alone upstream projects on fedorahosted.org.  In this case,
> Fedora is as much a downstream as RHEL and CentOS are.
>
> In the case of FreeIPA content, for example, I would expect the latter
> situation would probably occur.  We could want to use some or all of
> the FreeIPA content in, for example, a Fedora Deployment or Fedora
> Administration Guide.  Downstream appliance makers could use:
>
>   (FreeIPA + Fedora) - (cruft) - (Fedora mark) + (Fedora Remix mark)
>   
thanks for the thoughts.
> - Karsten
>   


-- 

David O'Brien
IPA Content Author
Red Hat Asia Pacific

"We couldn't care less about comfort. We make you feel good."
Federico Minoli CEO Ducati Motor S.p.A.