I have agreed to "honcho" a session for the Open Data Kit convening on documentation (specifically of the ODK suite). But I don't actually know that much about the documentation workflows in the project. Who does? What can folks share here? What would be good things to focus our time on during the session?
1 Like
It's bound to be a great discussion!
@adammichaelwood spearheaded the latest major structuring effort on the docs and set up the infrastructure and tech stack. He's at Google full time now so there hasn't been someone specifically focused on the docs for a while. You can see a lot of the thinking that went into various high level decisions by reading the posts in this category. I bet that Adam would be willing to answer a question here and there if his perspective would be helpful!
New features typically get documented by the developers who participate in them. The backlog is also mostly addressed by developers in a spare moment here and there but it has now become quite extensive. Every once in a while, a user will contribute an edit. Review is mostly done by @yanokwa or me.
Is this what you mean by workflow? Or are you asking a technology question?
Documentation seems like the kind of thing that lots of folks could be involved in the same way that translations are. It hasn't been the case, though, so one thing that I think would be valuable to discuss in person is why that is and what can be done about it. Another (complementary) angle would be to spend some time actually going through docs tickets. A focused hour with several people involved could make a difference and build some momentum.
1 Like
Thank you for this info. Very helpful! I will check those threads.
I am curious about this as a theme for the meeting:
Are you basing this on experience? I am not an expert on OSS documentation but I fear that conceptualizing docs like translations could lead to a rather messy set of docs lacking in cohesion and structure. I suppose the cohesion part can be addressed with standards, and I believe @adammichaelwood helped to put those in place, which is good. But I still wonder if docs as closer to code than to translations, which are more amenable to being "sliced up" into very small tasks.
Happy to be overruled here. Just wondering what will best set us up for success. I wonder if we need someone to occupy a "Docs Bottomliner" role. Does such a role exist? It could (should?) be held by a TSC member...
1 Like
Vaguely. I'm thinking of large-scale writing projects like Wikipedia and the fact that documentation is what I'm most likely to contribute to other projects.
That's a good point. I can think of various processes to help with that. For example, perhaps all issues should have a suggestion for where the content should go or contributors could be encouraged to contribute text in an issue comment/Google doc for a maintainer to plug in. I'm not sure, but I do think it's a good topic to explore.
I'm intrigued! Do you mean someone who does review and maintenance looking specifically at structure and cohesion?
1 Like
We've been talking about doing work on docs generally at the Open Data Kit convening as well and I think I am now officially the honcho for that, so @tomsmyth we should coordinate! We have also been discussing how:
so would be great to put our heads together on that as well! While definitely some issues are tools specific, I think some of the on-boarding and structural issues would be great to tackle together. One of my motivations for taking this on is I haven't yet actually figured out how to follow all the directions to contribute to the docs, so have great lived experience on the barriers!
1 Like
Agreed.
I more meant that they would review all docs PRs (for ODK; ODK-X would have their own Bottomliner) and ensure that things stay organized.
1 Like
Agreed. Especially since the 'contributing' doc appears to be identical for ODK and ODK-X.
Should we make this a joint session? I can let the facilitators know (so they can update the schedule) if you're interested...
2 Likes
I think at least a short joint session would be great! We can discuss some of the barriers to contribution and larger structural challenges together. Will save the very tool-specific documentation issues for later 
@tomsmyth if you can organize with facilitators that would be awesome. Thanks!
2 Likes
Currently, we have it scheduled so TSC-2 track will be attending Tom's session on Day 2.
1 Like