rework documentation

[Will Kahn-Greene]

We have three separate audiences that we need to write
documentation for:


-  contributors (developers, hackers, themers, translators, ...)
-  site admin (someone who installs MediaGoblin on his/her server
   to use)
-  users (someone who sets up a MediaGoblin account, uploads
   photos, ...)

Currently, we have documentation in a few different places. We want
to migrate to the following:


1. contributor and project infrastructure documentation goes in the
   wiki.
2. site admin documentation goes in docs/ where it's built in HTML
   and Texinfo formats for release tarballs; site admin documentation
   is also available on
   `http://docs.mediagoblin.org/ <http://docs.mediagoblin.org/>`_
3. user documentation will be part of the MediaGoblin code probably
   as Jinja2 templates available through /help/ url or something like
   that

We want to do this for 0.0.5, but the most important stuff
initially is straightening out the contributor docs, then
straightening out the site admin docs, then writing user docs.

[Christopher Allan Webber]

Adding Sam Kleinman / tychoish to this.

Sam has started going through our restructured text stuff and
cleaning it up, which is super great. However, it looks like he's
of a differing opinion about the wiki / sphinx distinction, and
thinks that much of the stuff that we've started moving to the wiki
really does belong in the sphinx docs.

I'll admit that I'm having a lot of frustrations where I can't tell
when something's administrator oriented vs developer oriented and
it seems like maybe it's both, and I'm not sure how to reconcile
that in the docs. (I somewhat wonder if the wiki should be a bit
more of "down and dirty solutions" and the sphinx docs be combo but
cleanly differentiated admin + developer docs?)

One way or another though we should decide on a path forward and
just do it, instead of half-doing things. Sam seems to be
interested in taking the reigns and making things actually good and
consistent, and more than anything else, that's what's needed right
now.

I'm especially interested in getting these three pages down to one
page:


-  The orphaned and not-even-in-the-repository-anymore
   hackinghowto.rst
   `http://docs.mediagoblin.org/hackinghowto.html <http://docs.mediagoblin.org/hackinghowto.html>`_
-  The bloated wiki HackingHowto
   `http://wiki.mediagoblin.org/HackingHowto <http://wiki.mediagoblin.org/HackingHowto>`_
-  The cleaner but unfinished Development Quick Start guide
   `http://wiki.mediagoblin.org/Development\_quick\_start <http://wiki.mediagoblin.org/Development_quick_start>`_

[Sam Kleinman]

Agreed.

I think the differences between developers, users, anda
dministrators in the context of free software and particularly
given the implications and goals of free network services aren't
**necessarily** as distinct as they might be in other contexts. In
general I think documentation either describes **how** something
works (i.e. API documentation) or defines a **procedure** of some
sort. There's also a small amount of meta/structural text that
helps users figure out the "why"-type questions. (e.g. "Why
do/should I care about this functionality," "Why do I need to read
this?") as well as the necessary "signposting," to guide users to
the documentation that they need the most.

Most of the stuff I've been doing so far has been to work on the
"Why" questions about the project, participation, documentation
structure, and so forth. I hope to move to documenting
functionality and procedures both continue to evolve.

Ideally, I think it would be best if the manual had all of the
functional and procedural material, and the wiki (or even the
website,) could focus more on the meta-layer stuff (how to
participate, community organization, development procedures.)

In practice, however, I think my tendency is to err on the side of
putting things in the manual (sphinx,) and use the wiki for a)
draft material, contributed by people who aren't me and for content
that is very explicitly **not** about the piece of software we're
building. Some of this content can and probably should be moved to
the website anyway, but I feel like the wiki can remain a mess as
long as the manual improves, the site improves, and the index page
of the wiki is updated regularly to provide appropriate
signposting.

In short: if it's about the mediagoblin software (usage,
functionality, development) I think it ought to go in the manual.
If it's about the community, organization, development procedures,
and brainstorming/drafting, I think it ought to stay in the wiki
(with the most static/important of this material moving up into the
website itself. There's overlap and there are cases where it's not
easily clean cut, but hyperlinks are cheap,

Anyway, that's my tendency, I'm willing to do the work to support
this, if that makes sense?

[Will Kahn-Greene]

So, I don't think this is a bad way of thinking about the docs, but
the audiences thing is really important because that's where people
looking at the docs are coming from. That's the way we need to have
the docs navigatable.

It's kind of a shame you're coming to the party late, so to speak.
The description of this issue comes from several months worth of
discussing the systems we have available, which system is best for
which kinds of workflow, and how to best achieve the short-term
needs we have. I don't think the changes suggested in the above two
comments really address any of that work.

So far most of the discussion has been on IRC and on the mailing
list. I threw this issue together based on the IRC meeting a few
weeks ago.

I'm +1 with Chris that whoever is going to do the work should have
more say in how it gets done. However, we seem to switch who's
going to do the work every couple of weeks and this documentation
overhaul is really suffering because of it with symptoms that Chris
is explaining.

So, if you're game for being the new documentation czar at least
until the end of the year and are planning to spend serious time on
it, I'm +1 with your plan. Otherwise, I'm not because I don't think
there's a compelling reason to switch the plan again.

[Christopher Allan Webber]

Will is right. We've changed this several times, and our last
change was based on a lot of thinking and discussion. If we do
change things again, we need to be confident that we're going to be
pushing full on forward in that direction, because more than
anything we need our docs to become coherent, and changing things
around has made them less so by a lot. If we do change again, we
also need to take into consideration some of the audience thoughts
we had earlier and not necessarily do the same things as we planned
but try to consider them appropriately in the new direction.

That said, I know Sam is extremely qualified for this, and again
what we really need is someone who's willing to push this forward
and be dedicated to it. Sam, if you're willing to take the reigns
here, lead our people out of a wasteland of terrible docs into the
promised land of documentation coherence, please assign this ticket
to yourself and I give you primary leadership over the particular
direction our docs end up going! And if not, then we'll go forward
with our original plans.

[Sam Kleinman]

So I am willing to do the work, but I don't want to come in and
have people feel cut out or ignored. I also respect that I'm
comparatively new and other folks might be invested in previous
plans. Thoughts:


-  I can't do this alone. I'm not a programmer, and although I have
   enough (a lot?) of documentation experience, at least for right now
   I don't trust myself to be able to figure out what needs
   documentation. I can do research to figure out most stuff, I can
   edit and organize, but I need other folks to send notes/drafts/and
   ideas for this to work. So even if this becomes "my thing," I don't
   want to overrule people or feel like people's earlier efforts were
   in vein.
-  Fewer places documentation could be means that there are fewer
   places to check, fewer search interfaces to use. Structure to
   document means that things are easier to find. That's sort of the
   overriding theme of how I approach documentation. I hope this
   solves many of the major issues.
-  I think it's possible to proceed in an iterative manner, without
   formally deciding on a new scheme. I can work on building out
   documentation, editing and revising the work we have now, etc., and
   other people can work in parallel with that and it's pretty easy to
   convert to/from rST, so all efforts will be useful and not in vein.
   We don't need to decide ideology right now...

I just made my first doc commit last night, Let's work on docs
things for a week (or two?) see what's there and reevaluate. Sound
good?

[Christopher Allan Webber]

Sounds lovely. :)

[Will Kahn-Greene]

Two things:


1. this bug has the beginning of an actual plan and part of the bug
   is to finish up the plan to finish up the documentation overhaul
   that was started in june/july

2. if you're just going to work through in an iterative manner with
   no plan, then this bug should be closed as rejected


Bumping this to the 0.1.0 target since we're done with 0.0.5 now.

[Christopher Allan Webber]

I'm marking this as closed and moving the target version back to
0.1.0. We actually discussed nicely on how to go forward with
reworking documentation and we put a plan into action starting with
0.1.0's work. I'm pretty happy with where things are going! We
should continue this work in other tickets.

[Will Kahn-Greene]

The original url for this bug was ​http://bugs.foocorp.net/issues/483 .
Relations:
#239: related