[Trisquel-devel] Documentation Team/Organization

[SirGrant]

Hey AndrewT,

I was looking at the documentation and we have a good start.  But I notice a
few issues.  Firstly, it is starting to get unwieldy.  There is some content
(e.g. http://trisquel.info/en/wiki/how-configure-zte-mf626-3g-modem) that
isn't what I think we should have.  Like with that example it isn't our job
to document how to get a modem how to work.  It is the people who make the
modem's job to document that.  Or it is a question for the forum. (I know
you didn't write that manual).

One other issue is with the way drupal sets things up.  If you check the
manual page (http://trisquel.info/en/wiki/manuals) for example "how to setup
a printer" appears twice.  Firstly in the making your hardware work section
and a second time on the bottom.  We need some sort of system to organize
the documentation section.  Jose Benito proposed an index system (
http://trisquel.info/en/wiki/index-proposal) based off Ubuntu's
documentation.  I think that is a good idea.  We should all maybe look it
over, make some changes where appropriate but having an index would add a
lot to organization.  Otherwise as the project grows we may get all sorts of
articles if we stay disorganized such as "how to configure AOL Instant
Messenger on Pidgin" which is really pidgin's documentation job.

Thirdly, since the documentation is setup in a wiki-style format where we
can all edit I think maybe we should adapt some sort of manual of style like
wikipedia has (
https://secure.wikimedia.org/wikipedia/en/wiki/Wikipedia:Manual_of_Style).
That way all our documentation pages will be consistent.  Because without it
if you write page X and I write page Y and BiFEO3 writes page Z I'm sure
they will come out totally different.  If we can agree on something it would
be a lot more professional and organized.  Also if I alter a page you wrote
we are less likely to get into squabbles about style.

The fourth thing I wanted to talk to you isn't that big of a deal but
something we should all maybe discuss in the future.  I was just looking at
one of the manuals on how to backup your files and you recommended a
different piece of software then I use (nothing wrong w/ that).  We should
maybe talk about a way to decide which software we recommend users use.  One
obvious rule would that it would have to be free software.  But some other
things we should discuss would be does the software support freedom.  By
that I mean do they consider themselves an open-source project or a free
software project.  Also which software is more robust.  Should we always
recommend GNU software over others such as GNU Social vs Diaspora?  I have
some ideas but no firm answers to any of these questions and I think it's
something everyone involved w/ the documentation team should discuss.

Lastly, I was talking to Quidam about one other way to get organized.  I
asked him about setting up a mailing list for people who want to work on the
documentation like you, BiFEO3, and myself.  For now he just said we could
use the trisquel-dev mailing list because it has virtually no traffic.  If
we start using it, it might draw attention.  Then in the future if it starts
becoming too much he may make a separate list just for us like
trisquel-doc.

I'm going to CC this message to Trisquel-dev.

--------------------Additional Comments --------------
I wrote this before I joined the trisquel-dev list.  I just read some
comments about documentation that have been posted.  I want to reply to some
of the things mentioned before on this list since I just joined.

1) I think we should assume the "average user" when we write our
documentation.  This goes into the manual-of-style idea of what level should
we write at.  I think assuming basic knowledge is reasonable because if we
write the documentation to be too simple the documentation will lack depth.
If we write to a power-user everyone else will be left out and things will
go over people's heads.

2) In terms of some of the response to Jose's proposed list.  I still think
the idea is valid.  Right now it's a proposal. One of the arguments are that
it contains too much information for the manpower we have.  That is a valid
argument.  We should in that case ALTER the proposal and remove
non-necessary stuff.  However I do think we need some sort of OUTLINE of
where the documentation should go/be about.  Otherwise we just have a group
of people creating manuals about whatever they want with no cohesion.  I
think we should all look at Jose's proposal.  Take out all the extra stuff
and get a good starting documentation working.  There is no reason to say we
can't add stuff later.  I know it's a lot of work but this is what we all
signed up for right?  We are the underdogs afterall.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listas.trisquel.info/pipermail/trisquel-devel/attachments/20110118/64969227/attachment.htm>