[FM Discuss] Does FLOSS Manuals hurt other doc efforts?

[adam]

hey

interesting thoughts :) i want to play devils advocate a little if i
may...

On Tue, 2010-11-23 at 13:21 -0800, Jennifer Zickerman wrote:
> I can think of a few ways that FLOSS Manuals might hurt a product's 
> documentation efforts:
> 
> - FLOSS Manuals might tempt some projects to reduce the resources they 
> commit to  documentation. If a project relies too heavily on FLOSS 
> Manuals for documentation, it is vulnerable if the FM volunteers lose 
> interest. Also, because the FLOSS Manual volunteers generally aren't as 
> tightly integrated with the project's developers as in-house writers, it 
> is harder for them to write docs that rely on developer input (such as 
> API or developer docs or even docs that describe changes in a particular 
> release).

so...heres my devilish rebuke to this point ;) on the point of
integration with inhouse writers.... i have found in some circumstances
exactly the opposite especially in book sprints. There have been two
that come to mind. First, the FM Ogg Theora Book Sprint where 2
developers of separate ogg transformation tools where part of a sprint
with 4 or so 'heavy users'. This conversation between devs (across 2
projects) and between devs and users was very rich. These devs are
'sole' developers so they do not have a team of inhouse writers and they
would not normally (I believe) have the chance to talk to 'the doc
writers' because there weren't any for their projects.

This might seem like I am slipping the argument sideways since this is a
situation unlike what you are referring to Jennifer. However I have also
seen the same happen in larger projects. I believe there are many on the
list from CiviCRM and they can talk to this if they are reading this
thread, and without putting words in their mouths I would say that many
fantastic conversations opened between devs and doc writers occurred in
the last sprint since there was a doc sprint in parallel to the book
sprint. There was a fantastic back and forth flow of information and
ideas which included times when the devs would sit back and think about
some of the points the doc writers raised. In some situations the issues
raised at the book sprint were solved on the spot by the devs.
Additionally the doc writers could pick the brains of the devs to
clarify issues they were writing about. Thats pretty tight integration.

So...on the other point you raise above (relying on FM docs). I would be
surprised if there are any projects out there that rely on FM for their
docs. I don't think I have been approached by anyone that felt they
could wave an empty FM manual in the air and have the FM community fill
it up. What I have seen is projects approach me and ask how to go about
getting their manual on FM because:
1. they like the tool set
2. they can see how FM might add to their existing energies

I don't see any projects slipping a project into FM and saying 'make me
a manual' to the FM community. This is why we encourage manuals to have
maintainers - because someone has to take responsibility for getting the
show going and keeping it going. When projects approach me about 'being
in FM' this is what I tell them - they must not see it as a magic wand,
but it can help if they take responsibility for generating the energy
and 'leveraging' that energy through the FM community to build on their
efforts.

Having said that I think there is actually an associated concern and one
I ponder frequently. There are projects that have docs in FM that have
no other docs. Ogg Theora is a good example. We did this sprint because
no one else had generated these docs and Ogg 'deserves' this support. I
don't think the Xiph crew rely on FM but if we didnt do the docs no one
else would. That might be a fine nuance to make but I think its an
important one and it is the difference between seeing a FM doc project
as either supplying docs that should exist but don't or developing docs
that projects rely on. I think we have always done the former, but I
would welcome any experiences/opinions/anecdotes that can straighten me
out on that if I have it wrong. 

My concern with developing docs for projects that dont have docs is that
we need to find the resources to maintain them. The Ogg Theora docs are
a year old, still relevant, but needing maintenance. So far no one has
picked this up. So what do we do? My strategy is too keep looking for
synergies or interested people to keep docs like this going but for some
projects it is harder than others. Synergy seems to be the key for
keeping this kind of doc effort alive.




> 
> - Having multiple sources of documentation can be inefficient to 
> maintain. If there is an FM Manual and a manual provided by the project, 
> two sets of  documentation need to be updated. If one or the other isn't 
> maintained, readers have to try to guess which is  accurate.

I think you are talking from the position that there should be 'one' set
of docs. Its not a position I agree with since I do not believe there
is :
1. 'one' type of reader
2. a shortage of free software docs in the world

> 
> - FLOSS Manuals might poach contributors from a project. It is fun and 
> easy and rewarding to participate in the FLOSS Manuals project and the 
> FM community is positive and supportive. Unfortunately this sometimes 
> isn't the case with open source projects, especially for technical 
> writers. While I hope that FLOSS Manuals will result in a bigger 
> contributor pool, it could also make some people switch from 
> contributing to core projects to working on FM.

i think 'poaching' would be a sin for FM. If anyone went out of their
way to tempt writers from another project to ditch their project and
work for FM I would personally like to kick their ass. 

But i do not think what you describe is 'poaching'. I would say it is a
symptom of a project failing to dedicate enough energy to their own doc
writers, failing to appreciate what they do, and then losing them as a
consequence. its a bit harsh to say 'FM' could cause these people to
leave and a lot harsh to call this 'poaching'. I think in this situation
the neglected writers would probably just stop contributing to their
chosen project and maybe spend their time with the kids, learning a new
language, reading...(whatever people do with real lives ;) 


> 
> I think one way around some aspects of these potential problems is to 
> distinguish between different kinds of documentation and figure out 
> which group can manage which type best. I'm on the Thunderbird team, so 
> this analysis applies to our project but may not apply to others:
> 
> - We have one part-time writer (me) who deals with both end-user 
> documentation and  editing API / developer documentation. There is no 
> way that we have the resources to contemplate doing a user manual, so 
> the FLOSS Manual is a *huge bonus* for us. For the foreseeable future 
> the Thunderbird FLOSS Manual will be the only manual, so there will be 
> no content duplication (although there may be issues with keeping it up 
> to date).
> 

thats very good news. I think the thunderbird manual is a great example
of a working synergy and i was what i had in mind when I talked of
creating synergies above.

> - Our primary goal with end-user documentation is to address the most 
> common questions we get in our support forums. Therefore, I put most of 
> my effort towards our Knowledge Base, which consists of short 
> problem-solving or how-to articles. This is a different type of 
> documentation from a manual, and serves a different purpose.
> 
> - Right now we don't have a lot of documentation contributors we might 
> lose to FM. This could be a problem for us in the future. We very much 
> want to expand the number of contributors to our core project. Hopefully 
> it will be self-organizing - some people will prefer to work on the FM 
> manual, while others will be more interested in developer docs or 
> support articles.


I would say that you should try and poach FM people! Try and convince
them to ditch FM and write for the thunderbird doc pages. Personally, I
have no problem with that. I think though what we are seeing emerge is a
mature relationship between FM and the Thunderbird doc efforts.
Thunderbird is a good example of this and another is CiviCRM where they
will start distributing the book generated in the book sprint with the
software....these collaborations and synergies is where FM is starting
to get interesting I would say...

adam

> 
> 
> 
> Jennifer Zickerman
> Documentation Wrangler
> Mozilla Messaging
> 
> On 17/11/10 4:08 AM, Scott Nesbitt wrote:
> > This is something that Adam and I have been discussing in a few emails,
> > and now it's time to take the idea to the wider list for comment.
> >
> > Here's the background: last month, I did a presentation about FLOSS
> > Manuals at the Free Software Open Source Symposium. During the
> > presentation (and a couple of times during the day) people asked me if
> > FLOSS Manuals drives people away from the "official" documentation. I
> > try to explain that one of the goals of FLOSS Manuals is to get people
> > up and running with whatever technology quickly and in a very friendly
> > way. But FMs don't cover everything -- FLOSS Manuals gets you going. If
> > you want to delve deep, deep into the software or technology, the
> > official docs are still there. That seems to get them even more interested.
> >
> > But that question showed something of a gap in perception, IMO. In my
> > mind, it's not FLOSS Manuals vs. the official documentation or other
> > docs/sources of information. There's not such thing as too much
> > documentation and no one source can be THE source. FM doesn't try to be
> > the last word in documentation. It doesn't answer all the questions or
> > have all the information. The FM should (and usually does) point people
> > to other sources of documentation so they can get a deeper view.
> >
> > So, what are your thoughts on this? Does FLOSS Manuals hurt, hinder, or
> > put into the shade other documentation efforts? Or are we one big
> > ecosystem, living in something akin to symbiosis (or commensalism)?
> > Let's get some discussion going!
> >
> > I'm looking forward to your comments. Which, unfortunately, I won't be
> > able to read until this evening (Eastern time) :-)
> >
> > Scott
> >
> >
> >
> > _______________________________________________
> > Discuss mailing list
> > Discuss at lists.flossmanuals.net
> > http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
> 
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net