Helder Ribeiro

Um problema que vamos enfrentar com certeza no Meu Parlamento é o quão complicado é o Processo Legislativo. Existe um número enorme de trajetos diferentes que uma proposição pode percorrer, e não é nada trivial saber o que cada etapa significa. A Câmara dá uma explicada e tem bastante coisa para ler no Interlegis, mas nada que se possa chamar exatamente de intuitivo. Também não é nada fácil olhar a tramitação de uma proposição em particular e entender onde ela está, por onde ainda falta passar, etc.

Eu pensei em um jeito de resolver estes dois problemas.

A idéia

A idéia é fazer um diagrama de estados completo e interativo, mostrando os estados e transições pelos quais uma proposição pode passar.

Aprendendo o Processo

Nas transições, as arestas tem a espessura proporcional ao número de proposições que já fizeram essa transição (a la Charles Joseph Minard). Os dados viriam do Legisdados.

Passar o mouse por cima da aresta a destaca e mostra um balão com sua descrição.

Passar o mouse por cima de um estado o destaca e mostra sua descrição.

Clicando o botão Play (tem um botão Play), começamos com uma nova proposição no estado inicial. Um texto explicativo é exibido embaixo, como se fosse uma visita guiada, falando o que aquele estado significa e explicando o que pode acontecer com a proposição a partir dali (isto é, descrevendo as arestas). Neste ponto, o usuário escolhe e clica em uma das arestas, passando para o próximo estado.

Repetindo estes passos, o usuário tem uma simulação completa da tramitação de uma proposição, explicada do começo ao fim. A espessura das arestas indica o caminho mais frequente e pode ser usado como dica para o usuário explorar primeiro os casos mais comuns.

Podemos pegar algumas proposições reais que sejam particularmante representativas ou históricas e ilustrar da mesma forma, com texto específico para ela, o caminho que seguiu. [Em vez de deixar o usuário clicar nas arestas, fazemos apenas um playback, exibindo um botão de "avançar".] Dessa forma sedimentamos o aprendizado com um exemplo real.

Acompanhando proposições

Para acompanhar a tramitação de uma proposição específica, mostramos o diagrama de estados um pouco apagado, destacando a trajetória já percorrida pela proposição. Nos balões de informação das arestas e estados, podemos colocar informações específicas daquela proposição. Por exemplo, na aresta poderíamos ter: “enviado para a Comissão de Constituição de Justiça em 05/03/2009″; e no estado: “na Comissão de Constituição e Justiça – relator Deputado João da Silva”.

O balão de informação do estado “votação” poderia mostrar um gráfico bonitão do resultado, como os do Congresso Aberto.

E podemos disponibilizar a mesma função de playback que descrevi acima: começamos na apresentação do texto, e cada click no botão de “avançar” vai para o estado seguinte, mostrando informação sobre a aresta tomada e o estado atingido.

Podemos também dar um leve destaque para os caminhos que a proposição ainda pode vir a percorrer.

A chamada

Eu sou um zero à esquerda para coisas gráficas. Eu posso programar a lógica do negócio, integrar aos dados, etc., mas não consigo nem fazer um mockup para ilustrar a minha idéia.

Então se você é um designer gráfico (especialmente se entende de animações em browser, com flash ou javascript) e quer dar uma mãozinha à democracia, entre no grupo de discussão do Meu Parlamento e diga alô :)

Talvez já haja coisas mais ou menos prontas que a gente possa reaproveitar. Eu encontrei este software que aparentemente transforma fluxogramas em animações flash, mas é proprietário, e não deve ser muito extensível. O ideal seria uma biblioteca, framework, alguma coisa assim que desse pra gente programar e adaptar.

Sugestões e críticas sobre a conceituação do negócio também são bem-vindas, tanto nos comentários quanto no grupo.

E se você resolver implementar a idéia por conta própria, pelo amor de deus libere o programa sob uma licença livre e mande o link :)

I wish there were a Firefox extension that did this:

1. you enter a list of RSS feeds;
2. it keeps track of which items you haven’t read yet;
3. you click a button or menu item and BAM!, it opens one tab for each unread item, showing the original page, not the RSS text content.

Disclaimer: this is a bunch of vaporware.

Read/Write Asymmetry

It’s been a while since people solved the problem of making API documentation easily readable, while keeping it closely tied to the code: keep it in comments in the source code and export it to HTML.

One problem that still remains is that developers suck at writing documentation. They have no need for it (it’s just a waste of time: they already know how that stuff works), and they often don’t use the API they develop themselves, or at least not in all possible use cases, so they end up not knowing very well which information is most valuable to the users.

Users, on the other hand, know it all too well. They know a hack around that quirky behavior; they inadvertently found that undocumented feature (or was it a bug?); they have collectively field-tested it in a hundred times as many use cases as the author had originally foreseen; and they know what needs to be known.

They write about it too! You can see countless blog posts, forum answers, even comments appended to the documentation itself taking up where it left off. It just happens that this stuff never makes its way back into the official docs because it’s too much of a hassle!

If you’re just a user of some library, you usually have it installed in some far-away system directory, outside of source control, and read-only. Making a change to the documentation means finding where the repository is hosted, checking it out locally, finding where in the code that bloody method is implemented, making a change and sending a patch (where to, again?). That’s not your job right?

So why don’t we just make it all a wiki huh? Easy as pie. No funky markup in comment blocks, no generation step, it’s all HTML. You’re reading it, you spot something wrong or incomplete, edit it right there and you’re back to reading before you can say “back to reading.” And where is the code now? Well, somewhere completely dissociated from the documentation. You’re not even sure which version you’re reading about.

So what we really want is API documentation that:

• comes directly from the source code;
• is easily editable as a wiki;
• and goes back to the source code.

There and Back Again

Rdoc.info takes any arbitrary repository and generates API documentation for you. So far it only works for Ruby repositories on Github, but it’s the only one I know so it’s the one I’ll talk about. The idea is applicable to anything that does the same type of auto-generation though.

That’s really cool then! Our first requirement is covered.

The second requirement is making a wiki, so I think we can borrow from about five million solutions.

Now HOW?! How do you turn that stuff back into source code again?!

chmod +w RDoc

Documentation on rdoc.info is generated per repository, per user, so you can decide, for each repository, if its documentation should be wiki-editable or not (if you made it this far I assume you really want it really bad). In that case, all you have to do is create a public branch called “docs”, and rdoc.info starts tracking that instead of the master branch, generating a wiki from it. Now you just tell everyone to come and edit!

Gathering edits

Rdoc.info forks your repository and commits every wiki edit to that fork. It’s quite simple: it just replaces the comment block next to a method/class/whatever with the edited version. On every commit, you receive a pull request.

Displaying

On the website, rdoc.info shows the latest wiki-edited docs by default, with a read-only “canonical” tab showing the last official version that was pushed before the recent edits.

Merging back

When you receive the pull request from rdoc.info, you merge rdoc.info’s branch back into yours, resolving possible conflicts and integrating the changes.

Edit History

What if you push to your “docs” branch when there are wiki commits that you haven’t integrated? Rdocs.info can’t try a normal merge, as there might be conflicts, and the whole thing has to be automatic. If it just does a “reset hard”, it’ll lose previous edits. So it does a merge, but with a no-hostages approach: automatically resolve every conflict by choosing your changes. It will count as a normal edit in the wiki, with the previous version still in the history.

Reverting to a particular version from the wiki interface is the same thing: the contents (only the doc comments, not the code) of the chosen version are commited on top of the current commit, and can be diffed with it.

Attribution, Statistics, Reputation

If the user making the edit is logged in, the commit can have her as the author, and statistics can be kept on who helped out the most and that kind of stuff. Methods with the least content can be marked as “stubs”, and editing those can be worth more points.

More into metadata territory, the developer could also possibly benefit from indirect usage statistics (through clicks and searches), and people up/downvoting individual methods, maybe even commenting on their design (whether they should be split in two; if the parameters or return values make sense, etc.).

You want it too?

From the few services I know which host API docs, I think the most likely to implement something like this are either rdoc.info or ApiDock. So write them and ask for it! (hey, I told you it was vaporware.)

Update: Apparently, something like this has been tried already by DocBox as a Google Summer of Code project. The code on Github is from last year and the website pointed at by RubyFlow seems to be down. Anyone with more info on this?

So I’m starting to get a kind of reputation for producing a lot of vaporware. According to wikipedia,

“most vaporware would not be considered a hoax since the makers have a genuine intention to create their product, even if it ultimately never materializes.”

Every once in a while I email friends with a cool idea I had, but it seems that I can produce ideas faster than code implementing them. That can be a cause of frustration if you think you’re the only person who can implement your ideas. And I usually don’t blog about them because it’s better to come out announcing something that actually exists.

I’m leaving that pride behind. I’ll just post ideas as they come. Since they’re not likely to get implemented by me anyway, at least there’s a slightly higher chance that someone else will like the idea, take it for themselves and run with it.

It’s kind of what organizations in the Google Summer of Code do. They post ideas, students come by, look at them, some decide to implement their own, some pick one from the list. This is the start of my own list of ideas. Maybe someday I’ll also have money to pay people to implement them like Google does.

I’ll take comfort in the fact that wikipedia also states that

“products with unspecified release dates (…) are not normally labelled vaporware.”