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

[Jennifer Zickerman]

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).

- 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.

- 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 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).

- 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.



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