[Trisquel-devel] Documentation Team/Organization

[Andrew Ter-Grigoryan]

On Tue, 2011-01-18 at 18:47 -0800, SirGrant wrote:
> 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).

For I while I have also thought the focus of that modem manual is just
too narrow to merit inclusion. With all due respect to the writer of
that manual, the choice of style for that manual needs a lot of
improvement, parts are outdated (like the reference to Ali Gunduz's
kernels), and it only applies to one specific model of hardware. For
those reasons, I didn't include it in the table of contents. With that
said, I wonder if Ruben be OK with deleting it?
> 
> 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.

I agree, having the manuals listed twice like that gives the page a
tentative and poorly maintained look. I'm going to move those manuals to
a new subdirectory so they will be out of sight and make the page look
cleaner. With the Drupal wiki system we have, I'm not sure there is a
better alternative than this right now.

If you take a close look at the table of contents I recently added to
the Manuals page, I have tried to adopt as much useful information from
the Ubuntu beginners' book while cutting out the more trivial stuff and
generally trying to condense as much as possible (for example, I want
the internet security and safety sections of that Ubuntu book to be
adapted into the "Staying secure and protecting your privacy" manual,
which hasn't been written yet). If somebody has any more suggestions for
useful things we can add to the table of contents, I'm glad to hear
them.
> 
> 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.

This would be a good idea in the future. We're slowly becoming more
organized across the board, so eventually it will become necessary.
Obviously, it wouldn't need to be anywhere near as detailed as the one
for Wikipedia, since the scope of a general encyclopedia wiki is vastly
greater than the one for our manuals. But up to now, I have applied a
sort of ad-hoc manual style of what I think looks reasonably neat to our
various manuals. Before I started working on the Trisquel documentation,
we had very few manuals, and they were written by a few different users.
The formatting on some of them was just plain bad (like the
aforementioned ZTE MF626 3G Modem manual, which I never got around to
correcting for 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.    

Yes of course, we never ever recommend non-free software.

The reason I chose Deja Dup was because it's so simple and intuitive
that even a computer newbie can start using it painlessly. Other backup
applications I've tried aren't as good at hiding the complexity of doing
backups behind a really neat GUI.

If our criteria is to favor more explicitly "free software" projects and
to favor GNU software, then Deja Dup would also fit the criteria,
because it is part of the GNOME Project, which is part of the GNU
project, which is -the- free software project of free software projects.

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

Yeah, right now the trisquel-devel mailing list has so little traffic,
it's the only one we need.
> 
> 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.

I think our manuals should assume two main groups: the GNU/Linux novice
and the power user. Most of the manuals apply to the former, and these
are the manuals that will largely overlap with Ubuntu's beginner
documentation. Manuals for the latter are grouped under the "Power-user
guides" section of the table of contents, and they show how to use
Trisquel to do various kinds of cool, difficult, and geeky things that
they may not have known was possible. I think both types of manual have
their place.

Thanks for your feedback, SirGrant!