Opened 12 years ago
Last modified 11 years ago
#189 closed task (FIXED)
|Reported by:||Will Kahn-Greene||Owned by:||Sam Kleinman|
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.
Change History (10)
comment:1 by , 12 years ago
comment:2 by , 12 years ago
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?
comment:3 by , 12 years ago
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.
comment:4 by , 12 years ago
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.
comment:5 by , 12 years ago
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?
comment:6 by , 12 years ago
Sounds lovely. :)
comment:7 by , 12 years ago
|Milestone:||0.0.5 → 0.1.0|
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.
comment:8 by , 11 years ago
|Milestone:||0.1.0 → 0.2.0|
comment:8 by , 11 years ago
|Milestone:||0.2.0 → 0.1.0|
|Status:||New → Closed|
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.
comment:9 by , 11 years ago
The original url for this bug was http://bugs.foocorp.net/issues/483 .
Note: See TracTickets for help on using tickets.